docs(decisions): Checkstyle posture — turn it on advisory now; how strict do we want it? (#272)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Paulo Gomes da Cruz Junior <paulo.cruz@gov.bc.ca>
Co-authored-by: Cooper <sofia.cooper@cgi.com>

Author: 4 people

.github/workflows/analysis.yml

@@ -35,7 +35,7 @@ jobs:
           # provides: AbstractOracleIT starts one gvenzl/oracle-free container per JVM and applies
           # the test snapshot with Flyway's Java API.
           commands: |
-            mvn -B -ntp -Dcheckstyle.skip=false -Dskip.integration.tests=false verify checkstyle:checkstyle
+            mvn -B -ntp -Dskip.integration.tests=false verify
           dir: backend
           java-cache: maven
           java-distribution: temurin

backend/.mvn/google_checks.xml

@@ -38,12 +38,6 @@
         <property name="eachLine" value="true"/>
     </module>
 
-    <module name="LineLength">
-        <property name="fileExtensions" value="java"/>
-        <property name="max" value="100"/>
-        <property name="ignorePattern" value="^package.*|^import.*|a href|href|http://|https://|ftp://"/>
-    </module>
-
     <module name="TreeWalker">
         <module name="OuterTypeFilename"/>
         <module name="IllegalTokenText">
@@ -238,14 +232,6 @@
             <message key="ws.notPreceded"
              value="GenericWhitespace ''{0}'' is not preceded with whitespace."/>
         </module>
-        <module name="Indentation">
-            <property name="basicOffset" value="2"/>
-            <property name="braceAdjustment" value="2"/>
-            <property name="caseIndent" value="2"/>
-            <property name="throwsIndent" value="4"/>
-            <property name="lineWrappingIndentation" value="4"/>
-            <property name="arrayInitIndent" value="2"/>
-        </module>
         <module name="AbbreviationAsWordInName">
             <property name="ignoreFinal" value="false"/>
             <property name="allowedAbbreviationLength" value="0"/>
@@ -257,12 +243,6 @@
         <module name="NoWhitespaceBeforeCaseDefaultColon"/>
         <module name="OverloadMethodsDeclarationOrder"/>
         <module name="VariableDeclarationUsageDistance"/>
-        <module name="CustomImportOrder">
-            <property name="sortImportsInGroupAlphabetically" value="true"/>
-            <property name="separateLineBetweenGroups" value="true"/>
-            <property name="customImportOrderRules" value="STATIC###THIRD_PARTY_PACKAGE"/>
-            <property name="tokens" value="IMPORT, STATIC_IMPORT, PACKAGE_DEF"/>
-        </module>
         <module name="MethodParamPad">
             <property name="tokens"
                       value="CTOR_DEF, LITERAL_NEW, METHOD_CALL, METHOD_DEF,

backend/Dockerfile

@@ -2,6 +2,7 @@ FROM maven:3.9.16-eclipse-temurin-21 AS build
 
 WORKDIR /workspace
 COPY pom.xml ./
+COPY .mvn ./.mvn
 RUN mvn -B -ntp -DskipTests dependency:go-offline
 COPY src ./src
 RUN mvn -B -ntp package

backend/pom.xml

@@ -61,14 +61,15 @@
         <skip.integration.tests>true</skip.integration.tests>
         <skip.unit.tests>false</skip.unit.tests>
         <jacoco.skip>false</jacoco.skip>
-        <checkstyle.skip>true</checkstyle.skip>
-        <checkstyle.failsOnError>false</checkstyle.failsOnError>
+        <checkstyle.skip>false</checkstyle.skip>
+        <checkstyle.failsOnError>true</checkstyle.failsOnError>
         <checkstyle.includeTestSourceDirectory>false</checkstyle.includeTestSourceDirectory>
         <cyclonedx.skip>false</cyclonedx.skip>
         <commons-lang3.version>3.20.0</commons-lang3.version>
         <jasperreports.version>7.0.8</jasperreports.version>
         <sonar.organization>bcgov-sonarcloud</sonar.organization>
         <sonar.host.url>https://sonarcloud.io</sonar.host.url>
+        <sonar.java.checkstyle.reportPaths>target/checkstyle-result.xml</sonar.java.checkstyle.reportPaths>
         <!-- Keep Sonar coverage measurement in step with the jacoco instrumentation excludes
              below: config/dto/exception/boilerplate are not instrumented, so counting them as
              uncovered would understate new-code coverage for lines jacoco never reports on. -->
@@ -510,6 +511,29 @@
                     </execution>
                 </executions>
             </plugin>
+            <plugin>
+                <groupId>com.diffplug.spotless</groupId>
+                <artifactId>spotless-maven-plugin</artifactId>
+                <version>2.44.3</version>
+                <configuration>
+                    <java>
+                        <googleJavaFormat>
+                            <version>1.25.2</version>
+                            <style>GOOGLE</style>
+                        </googleJavaFormat>
+                        <formatAnnotations />
+                    </java>
+                </configuration>
+                <executions>
+                    <execution>
+                        <id>spotless-check</id>
+                        <phase>validate</phase>
+                        <goals>
+                            <goal>check</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-checkstyle-plugin</artifactId>
@@ -532,7 +556,7 @@
                 <executions>
                     <execution>
                         <id>validate</id>
-                        <phase>checkstyle</phase>
+                        <phase>validate</phase>
                         <goals>
                             <goal>check</goal>
                         </goals>

backend/src/main/java/ca/bc/gov/nrs/ilcr/BackendConstants.java

@@ -4,46 +4,40 @@
 import lombok.NoArgsConstructor;
 
 /**
- * Application-wide constants: SQL parameter placeholders, sentinel values, and shared
- * security path lists.
+ * Application-wide constants: SQL parameter placeholders, sentinel values, and shared security path
+ * lists.
  *
  * <p>The token values in this class indicate an absent or unspecified value (for example when
- * binding query parameters) and a placeholder client identifier used when no client is
- * available. The path arrays centralize the request matchers referenced by the security
- * configuration.</p>
+ * binding query parameters) and a placeholder client identifier used when no client is available.
+ * The path arrays centralize the request matchers referenced by the security configuration.
  *
- * <p>This class is not instantiable and only exposes static constant values.</p>
+ * <p>This class is not instantiable and only exposes static constant values.
  */
 @NoArgsConstructor(access = AccessLevel.PRIVATE)
 public class BackendConstants {
 
   /**
    * Token representing a missing or unspecified value when interacting with legacy queries.
    *
-   * <p>Used in SQL where clauses and parameter binding to indicate the absence of a filter
-   * value.</p>
+   * <p>Used in SQL where clauses and parameter binding to indicate the absence of a filter value.
    */
   public static final String NOVALUE = "NOVALUE";
 
   /**
    * Token representing the absence of a client value.
    *
-   * <p>Used as a fallback client identifier in places where a client list is required but
-   * none are available.</p>
+   * <p>Used as a fallback client identifier in places where a client list is required but none are
+   * available.
    */
   public static final String NOCLIENT = "NOCLIENT";
 
   /**
    * Paths permitted without authentication regardless of whether security is enabled.
    *
-   * <p>Referenced by the security filter chain to allow the API root, health, info, and
-   * metrics endpoints.</p>
+   * <p>Referenced by the security filter chain to allow the API root, health, info, and metrics
+   * endpoints.
    */
   public static final String[] PUBLIC_PATHS = {
-    "/api",
-    "/api/health",
-    "/api/health/**",
-    "/api/info",
-    "/api/prometheus"
+    "/api", "/api/health", "/api/health/**", "/api/info", "/api/prometheus"
   };
 }

backend/src/main/java/ca/bc/gov/nrs/ilcr/HealthCheck.java

@@ -4,12 +4,18 @@
 import java.net.URI;
 import java.time.Duration;
 
+/** Simple application health check utility. */
 public final class HealthCheck {
   private static final int HEALTHY = 0;
   private static final int UNHEALTHY = 1;
 
   private HealthCheck() {}
 
+  /**
+   * Main entry point for the health check.
+   *
+   * @param args command line arguments
+   */
   public static void main(String[] args) {
     try {
       int port = Integer.parseInt(System.getenv().getOrDefault("SERVER_PORT", "8080"));

backend/src/main/java/ca/bc/gov/nrs/ilcr/IlcrBackendApplication.java

@@ -4,17 +4,23 @@
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 
+/** The main entry point for the ILCR Backend Application. */
 @SpringBootApplication
 public class IlcrBackendApplication {
 
-    public static void main(String[] args) {
-        // Anchor the JVM to Pacific BEFORE the context refreshes. The app serves the BC Ministry of
-        // Forests, but its OpenShift containers default to UTC, which shifts date boundaries
-        // (reporting-year rollover, SYSDATE/audit timestamps read as java.util.Date). Setting it here
-        // — ahead of SpringApplication.run — is deterministic: logging init, the Hikari pool, and every
-        // bean's @PostConstruct all observe Pacific, with no startup window left in UTC. Deploy may
-        // also set TZ=America/Vancouver on the container; this guarantees it even when it doesn't.
-        TimeZone.setDefault(TimeZone.getTimeZone("America/Vancouver"));
-        SpringApplication.run(IlcrBackendApplication.class, args);
-    }
+  /**
+   * The main method to start the Spring Boot application.
+   *
+   * @param args the command line arguments
+   */
+  public static void main(String[] args) {
+    // Anchor the JVM to Pacific BEFORE the context refreshes. The app serves the BC Ministry of
+    // Forests, but its OpenShift containers default to UTC, which shifts date boundaries
+    // (reporting-year rollover, SYSDATE/audit timestamps read as java.util.Date). Setting it here
+    // — ahead of SpringApplication.run — is deterministic: logging init, the Hikari pool, and every
+    // bean's @PostConstruct all observe Pacific, with no startup window left in UTC. Deploy may
+    // also set TZ=America/Vancouver on the container; this guarantees it even when it doesn't.
+    TimeZone.setDefault(TimeZone.getTimeZone("America/Vancouver"));
+    SpringApplication.run(IlcrBackendApplication.class, args);
+  }
 }

backend/src/main/java/ca/bc/gov/nrs/ilcr/assignment/MillUserProfileXrefEntity.java

@@ -9,12 +9,13 @@
 /**
  * Spring Data JDBC row shape for {@code THE.ILCR_MILL_USER_PROFILE_XREF} — one submitter↔mill
  * assignment (Story 2.1, AD-3). FAM is the source of truth for identity: {@code USER_GUID} is the
- * FAM {@code custom:idp_user_id} (32-char IDIR/BCeID GUID, Story 1.0), with no FK to any user table.
- * {@code USER_DISPLAY_NAME}/{@code IDP_USERNAME} are snapshotted from FAM at assign time (Q5) so an
- * ended assignment whose user has left FAM still renders. {@code END_DATE} null ⇒ ACTIVE.
+ * FAM {@code custom:idp_user_id} (32-char IDIR/BCeID GUID, Story 1.0), with no FK to any user
+ * table. {@code USER_DISPLAY_NAME}/{@code IDP_USERNAME} are snapshotted from FAM at assign time
+ * (Q5) so an ended assignment whose user has left FAM still renders. {@code END_DATE} null ⇒
+ * ACTIVE.
  *
- * <p>{@link MillUserProfileXrefRepository} reads these; the service maps them to the wire
- * {@code MillSubmitter} DTO (Story 2.2 — entities never cross the service boundary).
+ * <p>{@link MillUserProfileXrefRepository} reads these; the service maps them to the wire {@code
+ * MillSubmitter} DTO (Story 2.2 — entities never cross the service boundary).
  */
 @Table(name = "ILCR_MILL_USER_PROFILE_XREF", schema = "THE")
 public record MillUserProfileXrefEntity(
@@ -29,5 +30,4 @@ public record MillUserProfileXrefEntity(
     @Column("ENTRY_USERID") String entryUserid,
     @Column("ENTRY_TIMESTAMP") LocalDateTime entryTimestamp,
     @Column("UPDATE_USERID") String updateUserid,
-    @Column("UPDATE_TIMESTAMP") LocalDateTime updateTimestamp) {
-}
+    @Column("UPDATE_TIMESTAMP") LocalDateTime updateTimestamp) {}

backend/src/main/java/ca/bc/gov/nrs/ilcr/assignment/MillUserProfileXrefRepository.java

@@ -11,21 +11,22 @@
  * named-parameter SQL). SQL only — decisions live in the service; entities never cross the service
  * boundary (the service maps them to the {@code MillSubmitter} DTO in Story 2.2).
  *
- * <p>Story 2.1 scaffolds the read side; the assign/end write methods and the mill-join enrichment are
- * added in Story 2.2. These reads are exercised (red) by Story 2.2's tests.
+ * <p>Story 2.1 scaffolds the read side; the assign/end write methods and the mill-join enrichment
+ * are added in Story 2.2. These reads are exercised (red) by Story 2.2's tests.
  */
 @org.springframework.stereotype.Repository
-public interface MillUserProfileXrefRepository
-    extends Repository<MillUserProfileXrefEntity, Long> {
+public interface MillUserProfileXrefRepository extends Repository<MillUserProfileXrefEntity, Long> {
 
   /**
-   * All assignment rows for a mill — active (END_DATE null) and ended — most-recently-started first.
-   * The service filters/derives status and joins {@code THE.MILL} for the mill number/name (2.2).
+   * All assignment rows for a mill — active (END_DATE null) and ended — most-recently-started
+   * first. The service filters/derives status and joins {@code THE.MILL} for the mill number/name
+   * (2.2).
    *
    * @param millId the {@code ILCR_MILL_ID}
    * @return the mill's assignment rows
    */
-  @Query("""
+  @Query(
+      """
       SELECT ILCR_MILL_USER_PROFILE_XREF_ID, USER_GUID, ILCR_MILL_ID, USER_DISPLAY_NAME, IDP_USERNAME,
              START_DATE, END_DATE, REVISION_COUNT, ENTRY_USERID, ENTRY_TIMESTAMP, UPDATE_USERID,
              UPDATE_TIMESTAMP
@@ -36,12 +37,14 @@ public interface MillUserProfileXrefRepository
   List<MillUserProfileXrefEntity> findByMill(@Param("millId") long millId);
 
   /**
-   * All assignment rows for a submitter (by FAM {@code custom:idp_user_id}) — the user-centric read.
+   * All assignment rows for a submitter (by FAM {@code custom:idp_user_id}) — the user-centric
+   * read.
    *
    * @param userGuid the FAM user GUID ({@code USER_GUID})
    * @return the submitter's assignment rows
    */
-  @Query("""
+  @Query(
+      """
       SELECT ILCR_MILL_USER_PROFILE_XREF_ID, USER_GUID, ILCR_MILL_ID, USER_DISPLAY_NAME, IDP_USERNAME,
              START_DATE, END_DATE, REVISION_COUNT, ENTRY_USERID, ENTRY_TIMESTAMP, UPDATE_USERID,
              UPDATE_TIMESTAMP

backend/src/main/java/ca/bc/gov/nrs/ilcr/assignment/dto/AssignSubmitterRequest.java

@@ -1,11 +1,11 @@
 package ca.bc.gov.nrs.ilcr.assignment.dto;
 
 /**
- * Wire shape for assigning a submitter to a mill (AD-12 pin, Story 2.1). The mill is a path variable
- * and the acting admin is the JWT principal, so the body carries only the submitter's FAM user GUID
- * ({@code custom:idp_user_id}). Consumed by Story 2.2's {@code POST /api/v1/mills/{millId}/submitters}.
+ * Wire shape for assigning a submitter to a mill (AD-12 pin, Story 2.1). The mill is a path
+ * variable and the acting admin is the JWT principal, so the body carries only the submitter's FAM
+ * user GUID ({@code custom:idp_user_id}). Consumed by Story 2.2's {@code POST
+ * /api/v1/mills/{millId}/submitters}.
  *
  * @param userGuid the FAM user GUID of the submitter to assign
  */
-public record AssignSubmitterRequest(String userGuid) {
-}
+public record AssignSubmitterRequest(String userGuid) {}