Make merged #289 training code pass SpotBugs + PIT (keep pure @builder)

The #289 merge introduced the first Lombok-@Builder-heavy class and it had not
cleared the strict quality gates:

SpotBugs (13 findings), all fixed while keeping class-level @builder:
- 10x MRC_METHOD_RETURNS_CONSTANT on Lombok's synthetic $default$*() methods:
  @Builder.Default emits these, and they are NOT tagged @lombok.Generated even
  with lombok.addLombokGeneratedAnnotation=true (a Lombok limitation), so
  SpotBugs cannot auto-skip them. Suppressed for the $default$* methods only.
- IMC_IMMATURE_CLASS_NO_TOSTRING: add @tostring (generated, @lombok.Generated).
- IMC_IMMATURE_CLASS_WRONG_FIELD_ORDER: move the static MAPPER above the
  instance fields.
- RCN_REDUNDANT_NULLCHECK in LlamaTrainer: the @NullMarked default treated the
  native finetuneNative() return as @nonnull; mark it @nullable (JNI can return
  null on success), making the `error != null` guard meaningful.

PIT (was 99% < 100% threshold):
- Optimizer.getNativeValue() showed as NO_COVERAGE because its only test lived in
  TrainingParametersTest (package parameters.*), outside PIT's args.*/value.*/
  exception.*/json.* targetTests. Move it to a dedicated args.OptimizerTest so
  PIT runs it. Score back to 100% (249/249).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Rt1paYztGJ2AKUuBuAGDXE

Author: claude

llama/spotbugs-exclude.xml

@@ -605,4 +605,21 @@ SPDX-License-Identifier: MIT
         <Method name="synthesize"/>
     </Match>
 
+    <!--
+        TrainingParameters uses Lombok @Builder with @Builder.Default on its schedule/optimizer
+        fields. For each defaulted field Lombok emits a synthetic static `$default$<field>()` method
+        that simply returns the default constant, which fb-contrib flags as
+        MRC_METHOD_RETURNS_CONSTANT. Unlike Lombok's accessor/constructor output, these
+        `$default$*` methods are NOT tagged with @lombok.Generated even when
+        `lombok.addLombokGeneratedAnnotation = true` (a long-standing Lombok limitation), so
+        SpotBugs cannot skip them automatically the way it does the rest of the generated members.
+        The methods are pure generated boilerplate — returning a constant is exactly their purpose —
+        so the finding is suppressed for these synthetic methods only.
+    -->
+    <Match>
+        <Class name="net.ladenthin.llama.parameters.TrainingParameters"/>
+        <Bug pattern="MRC_METHOD_RETURNS_CONSTANT"/>
+        <Method name="~\$default\$.*"/>
+    </Match>
+
 </FindBugsFilter>

llama/src/main/java/net/ladenthin/llama/LlamaTrainer.java

@@ -8,6 +8,7 @@
 import net.ladenthin.llama.exception.LlamaException;
 import net.ladenthin.llama.loader.LlamaLoader;
 import net.ladenthin.llama.parameters.TrainingParameters;
+import org.jspecify.annotations.Nullable;
 
 /**
  * In-process fine-tuning entry point, wrapping llama.cpp's ggml-opt training path
@@ -60,5 +61,8 @@ public static void finetune(Path model, String trainingText, Path output, int ep
                 .build());
     }
 
-    private static native String finetuneNative(String configJson);
+    // The native layer returns null on success and a non-empty error message on failure, so the
+    // return is genuinely @Nullable — without this the module's @NullMarked default would treat it
+    // as @NonNull and SpotBugs would flag the `error != null` guard as a redundant null check.
+    private static native @Nullable String finetuneNative(String configJson);
 }

llama/src/main/java/net/ladenthin/llama/parameters/TrainingParameters.java

@@ -9,6 +9,7 @@
 import java.nio.file.Path;
 import lombok.Builder;
 import lombok.Getter;
+import lombok.ToString;
 import net.ladenthin.llama.args.Optimizer;
 import org.jspecify.annotations.Nullable;
 
@@ -23,8 +24,13 @@
  */
 @Builder
 @Getter
+@ToString
 public final class TrainingParameters {
 
+    // Jackson mapper for JSON serialization. Static field declared before the instance fields
+    // to satisfy fb-contrib's IMC_IMMATURE_CLASS_WRONG_FIELD_ORDER (static members come first).
+    private static final ObjectMapper MAPPER = new ObjectMapper();
+
     // Base GGUF model to fine-tune.
     private final Path modelPath;
 
@@ -81,45 +87,6 @@ public final class TrainingParameters {
     @Builder.Default
     private final int nUbatch = 0;
 
-    private static final ObjectMapper MAPPER = new ObjectMapper();
-
-    // Explicit all-args constructor used by the Lombok-generated builder. Declared explicitly (rather
-    // than letting @Builder synthesize the package-private one) so Javadoc sees a real constructor and
-    // does not emit the "use of default constructor, which does not provide a comment" warning; it is
-    // private, so it is not part of the public API and is not doclint-checked.
-    private TrainingParameters(
-            Path modelPath,
-            @Nullable String trainingText,
-            @Nullable Path trainingFile,
-            Path outputPath,
-            int epochs,
-            float learningRate,
-            float lrMin,
-            float decayEpochs,
-            float weightDecay,
-            Optimizer optimizer,
-            int nCtx,
-            int nGpuLayers,
-            float valSplit,
-            int nBatch,
-            int nUbatch) {
-        this.modelPath = modelPath;
-        this.trainingText = trainingText;
-        this.trainingFile = trainingFile;
-        this.outputPath = outputPath;
-        this.epochs = epochs;
-        this.learningRate = learningRate;
-        this.lrMin = lrMin;
-        this.decayEpochs = decayEpochs;
-        this.weightDecay = weightDecay;
-        this.optimizer = optimizer;
-        this.nCtx = nCtx;
-        this.nGpuLayers = nGpuLayers;
-        this.valSplit = valSplit;
-        this.nBatch = nBatch;
-        this.nUbatch = nUbatch;
-    }
-
     /**
      * Serialize this configuration to the JSON object the native fine-tuning layer expects.
      *

llama/src/test/java/net/ladenthin/llama/args/OptimizerTest.java

@@ -0,0 +1,20 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: MIT
+
+package net.ladenthin.llama.args;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.is;
+
+import org.junit.jupiter.api.Test;
+
+/** Model-free tests for the {@link Optimizer} native-value mapping. */
+class OptimizerTest {
+
+    @Test
+    void nativeValuesMatchGgml() {
+        assertThat(Optimizer.ADAMW.getNativeValue(), is(0));
+        assertThat(Optimizer.SGD.getNativeValue(), is(1));
+    }
+}

llama/src/test/java/net/ladenthin/llama/parameters/TrainingParametersTest.java

@@ -70,10 +70,4 @@ void customValuesSerialize() throws Exception {
         // training_text is omitted when a corpus file is given.
         assertThat(node.has("training_text"), is(false));
     }
-
-    @Test
-    void optimizerNativeValuesMatchGgml() {
-        assertThat(Optimizer.ADAMW.getNativeValue(), is(0));
-        assertThat(Optimizer.SGD.getNativeValue(), is(1));
-    }
 }