Emit direct setter last within same-name builder method overloads

docs/CUSTOMIZING.md

@@ -275,20 +275,25 @@ compileJava {
 | [`StringFormatHelperGenerator`](../processor/src/main/java/org/javahelpers/simple/builders/processor/generators/field/StringFormatHelperGenerator.java) | String.format helpers | 80 |
 | [`SupplierMethodGenerator`](../processor/src/main/java/org/javahelpers/simple/builders/processor/generators/field/SupplierMethodGenerator.java) | Supplier-based setters | 80 |
 | [`VarArgsHelperGenerator`](../processor/src/main/java/org/javahelpers/simple/builders/processor/generators/field/VarArgsHelperGenerator.java) | Varargs helpers | 50 |
+| [`StringBuilderConsumerGenerator`](../processor/src/main/java/org/javahelpers/simple/builders/processor/generators/field/StringBuilderConsumerGenerator.java) | StringBuilder consumer methods | 45 |
 | [`ArrayConversionGenerator`](../processor/src/main/java/org/javahelpers/simple/builders/processor/generators/field/ArrayConversionGenerator.java) | Array-from-List conversion methods | 35 |
 | [`UpdateHelperGenerator`](../processor/src/main/java/org/javahelpers/simple/builders/processor/generators/field/UpdateHelperGenerator.java) | UnaryOperator update helpers | 31 |
 | [`AddToCollectionGenerator`](../processor/src/main/java/org/javahelpers/simple/builders/processor/generators/field/AddToCollectionGenerator.java) | add2FieldName methods for List/Set | 30 |
 | [`ArrayBuilderConsumerGenerator`](../processor/src/main/java/org/javahelpers/simple/builders/processor/generators/field/ArrayBuilderConsumerGenerator.java) | ArrayListBuilder consumer methods for arrays | 25 |
 
+The column is the generator's *execution* priority. Emission order inside the generated class is governed separately: constructors first, then methods sorted by their `ordering` value (creation methods 200, fluent field methods 1000, conditional helpers 1100, build 1200, toString 2000, private helpers 2100), then by access modifier (public first, private last), non-static before static, then grouped by originating field, and finally by method name. Within a same-named overload group the direct property setter is emitted last, so consumers that resolve overloaded builder methods last-wins — e.g. MapStruct's builder detection — bind to the plain setter.
+
 ### Builder-Level Generators
 
 | Generator | Purpose | Priority |
 |----------|---------|----------|
 | [`ConditionalEnhancer`](../processor/src/main/java/org/javahelpers/simple/builders/processor/generators/builder/ConditionalEnhancer.java) | Conditional logic methods | 100 |
 | [`JacksonAnnotationEnhancer`](../processor/src/main/java/org/javahelpers/simple/builders/processor/generators/builder/JacksonAnnotationEnhancer.java) | Jackson annotations | 100 |
 | [`CoreMethodsEnhancer`](../processor/src/main/java/org/javahelpers/simple/builders/processor/generators/builder/CoreMethodsEnhancer.java) | Core builder methods (build, create, toString) | 100 |
+| [`ConstructorEnhancer`](../processor/src/main/java/org/javahelpers/simple/builders/processor/generators/builder/ConstructorEnhancer.java) | Builder constructors (empty + from-instance) | 95 |
 | [`WithInterfaceEnhancer`](../processor/src/main/java/org/javahelpers/simple/builders/processor/generators/builder/WithInterfaceEnhancer.java) | With interface implementation | 90 |
 | [`InterfaceEnhancer`](../processor/src/main/java/org/javahelpers/simple/builders/processor/generators/builder/InterfaceEnhancer.java) | Builder interface implementation | 90 |
+| [`FieldPrefillEnhancer`](../processor/src/main/java/org/javahelpers/simple/builders/processor/generators/builder/FieldPrefillEnhancer.java) | Field-function prefilling for referenced builders | 15 |
 | [`GeneratedAnnotationEnhancer`](../processor/src/main/java/org/javahelpers/simple/builders/processor/generators/builder/GeneratedAnnotationEnhancer.java) | @Generated annotation | 10 |
 | [`BuilderImplementationAnnotationEnhancer`](../processor/src/main/java/org/javahelpers/simple/builders/processor/generators/builder/BuilderImplementationAnnotationEnhancer.java) | @BuilderImplementation annotation | 10 |
 | [`ClassJavaDocEnhancer`](../processor/src/main/java/org/javahelpers/simple/builders/processor/generators/builder/ClassJavaDocEnhancer.java) | Class-level JavaDoc | 10 |

example/generated-example-builder/org/javahelpers/simple/builders/example/ExternalAddressBuilder.java

@@ -95,25 +95,6 @@ public static ExternalAddressBuilder create() {
     return new ExternalAddressBuilder();
   }
 
-  /**
-   * Sets the value for <code>city</code>.
-   * <p>
-   * Generated from setter {@link ExternalAddress#setCity(String) setCity(String city)}
-   * 
-   * <h4>Example:</h4>
-   * 
-   * <pre>{@code
-   * builder.city("example value");
-   * }</pre>
-   * 
-   * @param city city
-   * @return current instance of builder
-   */
-  public ExternalAddressBuilder city(String city) {
-    this.city = changedValue(city);
-    return this;
-  }
-
   /**
    * Sets the value for <code>city</code> by executing the provided consumer.
    * <p>
@@ -176,47 +157,47 @@ public ExternalAddressBuilder city(String format, Object... args) {
   }
 
   /**
-   * Updates the current value of <code>city</code> in place by applying the given operator, instead of reading it out,
-   * changing it and setting it again. Useful for adjustments relative to the current value, e.g. trimming,
-   * upper-casing, clamping or incrementing, and in combination with the <code>With</code> copy-and-modify flow. The
-   * value must have been set before (directly or via an existing instance).
+   * Sets the value for <code>city</code>.
    * <p>
    * Generated from setter {@link ExternalAddress#setCity(String) setCity(String city)}
    * 
    * <h4>Example:</h4>
    * 
    * <pre>{@code
-   * builder.city("example value").cityUpdate(String::trim);
+   * builder.city("example value");
    * }</pre>
    * 
-   * @param cityUpdater operator applied to the current value; its result becomes the new value
+   * @param city city
    * @return current instance of builder
-   * @throws IllegalStateException if <code>city</code> has not been set yet
    */
-  public ExternalAddressBuilder cityUpdate(UnaryOperator<String> cityUpdater) {
-    if (!this.city.isSet()) {
-      throw new IllegalStateException("Cannot update 'city' before it is set");
-    }
-    this.city = changedValue(cityUpdater.apply(this.city.value()));
+  public ExternalAddressBuilder city(String city) {
+    this.city = changedValue(city);
     return this;
   }
 
   /**
-   * Sets the value for <code>street</code>.
+   * Updates the current value of <code>city</code> in place by applying the given operator, instead of reading it out,
+   * changing it and setting it again. Useful for adjustments relative to the current value, e.g. trimming,
+   * upper-casing, clamping or incrementing, and in combination with the <code>With</code> copy-and-modify flow. The
+   * value must have been set before (directly or via an existing instance).
    * <p>
-   * Generated from setter {@link ExternalAddress#setStreet(String) setStreet(String street)}
+   * Generated from setter {@link ExternalAddress#setCity(String) setCity(String city)}
    * 
    * <h4>Example:</h4>
    * 
    * <pre>{@code
-   * builder.street("example value");
+   * builder.city("example value").cityUpdate(String::trim);
    * }</pre>
    * 
-   * @param street street
+   * @param cityUpdater operator applied to the current value; its result becomes the new value
    * @return current instance of builder
+   * @throws IllegalStateException if <code>city</code> has not been set yet
    */
-  public ExternalAddressBuilder street(String street) {
-    this.street = changedValue(street);
+  public ExternalAddressBuilder cityUpdate(UnaryOperator<String> cityUpdater) {
+    if (!this.city.isSet()) {
+      throw new IllegalStateException("Cannot update 'city' before it is set");
+    }
+    this.city = changedValue(cityUpdater.apply(this.city.value()));
     return this;
   }
 
@@ -282,92 +263,47 @@ public ExternalAddressBuilder street(String format, Object... args) {
   }
 
   /**
-   * Updates the current value of <code>street</code> in place by applying the given operator, instead of reading it
-   * out, changing it and setting it again. Useful for adjustments relative to the current value, e.g. trimming,
-   * upper-casing, clamping or incrementing, and in combination with the <code>With</code> copy-and-modify flow. The
-   * value must have been set before (directly or via an existing instance).
+   * Sets the value for <code>street</code>.
    * <p>
    * Generated from setter {@link ExternalAddress#setStreet(String) setStreet(String street)}
    * 
    * <h4>Example:</h4>
    * 
    * <pre>{@code
-   * builder.street("example value").streetUpdate(String::trim);
+   * builder.street("example value");
    * }</pre>
    * 
-   * @param streetUpdater operator applied to the current value; its result becomes the new value
+   * @param street street
    * @return current instance of builder
-   * @throws IllegalStateException if <code>street</code> has not been set yet
    */
-  public ExternalAddressBuilder streetUpdate(UnaryOperator<String> streetUpdater) {
-    if (!this.street.isSet()) {
-      throw new IllegalStateException("Cannot update 'street' before it is set");
-    }
-    this.street = changedValue(streetUpdater.apply(this.street.value()));
-    return this;
-  }
-
-  /**
-   * Validates that the city field is not null or empty.
-   * <p>
-   * Generated from setter {@link ExternalAddress#setCity(String) setCity(String city)}
-   * 
-   * @return this builder instance for chaining
-   * @throws IllegalArgumentException if city is null or empty
-   */
-  ExternalAddressBuilder validateCity() {
-    if (!city.isSet() || city.value().trim().isEmpty()) {
-      throw new IllegalArgumentException("City cannot be null or empty");
-    }
+  public ExternalAddressBuilder street(String street) {
+    this.street = changedValue(street);
     return this;
   }
 
   /**
-   * Validates that the street field is not null or empty.
+   * Updates the current value of <code>street</code> in place by applying the given operator, instead of reading it
+   * out, changing it and setting it again. Useful for adjustments relative to the current value, e.g. trimming,
+   * upper-casing, clamping or incrementing, and in combination with the <code>With</code> copy-and-modify flow. The
+   * value must have been set before (directly or via an existing instance).
    * <p>
    * Generated from setter {@link ExternalAddress#setStreet(String) setStreet(String street)}
    * 
-   * @return this builder instance for chaining
-   * @throws IllegalArgumentException if street is null or empty
-   */
-  ExternalAddressBuilder validateStreet() {
-    if (!street.isSet() || street.value().trim().isEmpty()) {
-      throw new IllegalArgumentException("Street cannot be null or empty");
-    }
-    return this;
-  }
-
-  /**
-   * Validates that the zipCode field is not null or empty.
-   * <p>
-   * Generated from setter {@link ExternalAddress#setZipCode(String) setZipCode(String zipCode)}
-   * 
-   * @return this builder instance for chaining
-   * @throws IllegalArgumentException if zipCode is null or empty
-   */
-  ExternalAddressBuilder validateZipCode() {
-    if (!zipCode.isSet() || zipCode.value().trim().isEmpty()) {
-      throw new IllegalArgumentException("ZipCode cannot be null or empty");
-    }
-    return this;
-  }
-
-  /**
-   * Sets the value for <code>zipCode</code>.
-   * <p>
-   * Generated from setter {@link ExternalAddress#setZipCode(String) setZipCode(String zipCode)}
-   * 
    * <h4>Example:</h4>
    * 
    * <pre>{@code
-   * builder.zipCode("example value");
+   * builder.street("example value").streetUpdate(String::trim);
    * }</pre>
    * 
-   * @param zipCode zipCode
+   * @param streetUpdater operator applied to the current value; its result becomes the new value
    * @return current instance of builder
+   * @throws IllegalStateException if <code>street</code> has not been set yet
    */
-  public ExternalAddressBuilder zipCode(String zipCode) {
-    this.zipCode = changedValue(zipCode);
+  public ExternalAddressBuilder streetUpdate(UnaryOperator<String> streetUpdater) {
+    if (!this.street.isSet()) {
+      throw new IllegalStateException("Cannot update 'street' before it is set");
+    }
+    this.street = changedValue(streetUpdater.apply(this.street.value()));
     return this;
   }
 
@@ -432,6 +368,25 @@ public ExternalAddressBuilder zipCode(String format, Object... args) {
     return this;
   }
 
+  /**
+   * Sets the value for <code>zipCode</code>.
+   * <p>
+   * Generated from setter {@link ExternalAddress#setZipCode(String) setZipCode(String zipCode)}
+   * 
+   * <h4>Example:</h4>
+   * 
+   * <pre>{@code
+   * builder.zipCode("example value");
+   * }</pre>
+   * 
+   * @param zipCode zipCode
+   * @return current instance of builder
+   */
+  public ExternalAddressBuilder zipCode(String zipCode) {
+    this.zipCode = changedValue(zipCode);
+    return this;
+  }
+
   /**
    * Updates the current value of <code>zipCode</code> in place by applying the given operator, instead of reading it
    * out, changing it and setting it again. Useful for adjustments relative to the current value, e.g. trimming,
@@ -458,6 +413,51 @@ public ExternalAddressBuilder zipCodeUpdate(UnaryOperator<String> zipCodeUpdater
     return this;
   }
 
+  /**
+   * Validates that the city field is not null or empty.
+   * <p>
+   * Generated from setter {@link ExternalAddress#setCity(String) setCity(String city)}
+   * 
+   * @return this builder instance for chaining
+   * @throws IllegalArgumentException if city is null or empty
+   */
+  ExternalAddressBuilder validateCity() {
+    if (!city.isSet() || city.value().trim().isEmpty()) {
+      throw new IllegalArgumentException("City cannot be null or empty");
+    }
+    return this;
+  }
+
+  /**
+   * Validates that the street field is not null or empty.
+   * <p>
+   * Generated from setter {@link ExternalAddress#setStreet(String) setStreet(String street)}
+   * 
+   * @return this builder instance for chaining
+   * @throws IllegalArgumentException if street is null or empty
+   */
+  ExternalAddressBuilder validateStreet() {
+    if (!street.isSet() || street.value().trim().isEmpty()) {
+      throw new IllegalArgumentException("Street cannot be null or empty");
+    }
+    return this;
+  }
+
+  /**
+   * Validates that the zipCode field is not null or empty.
+   * <p>
+   * Generated from setter {@link ExternalAddress#setZipCode(String) setZipCode(String zipCode)}
+   * 
+   * @return this builder instance for chaining
+   * @throws IllegalArgumentException if zipCode is null or empty
+   */
+  ExternalAddressBuilder validateZipCode() {
+    if (!zipCode.isSet() || zipCode.value().trim().isEmpty()) {
+      throw new IllegalArgumentException("ZipCode cannot be null or empty");
+    }
+    return this;
+  }
+
   /**
    * Conditionally applies builder modifications if the condition is true.
    *