@sun-asterisk/sunlint 1.3.48 → 1.3.49

package/skill-assets/sunlint-code-quality/rules/java/J008-thread-safe-singleton.md

@@ -0,0 +1,119 @@
+---
+title: Implement Thread-Safe Singleton Correctly
+impact: HIGH
+impactDescription: a non-thread-safe singleton can create multiple instances under concurrent load, breaking application invariants
+tags: concurrency, design-pattern, java, thread-safety
+---
+
+## Implement Thread-Safe Singleton Correctly
+
+The Singleton pattern ensures a class has only one instance. In multi-threaded Java applications, a naive singleton implementation can create multiple instances when two threads enter `getInstance()` simultaneously. This is a classic race condition.
+
+**Incorrect (not thread-safe):**
+
+```java
+// Lazy initialization — race condition when two threads call getInstance() simultaneously
+public class ConfigManager {
+    private static ConfigManager instance;
+
+    private ConfigManager() {
+        loadConfiguration();
+    }
+
+    public static ConfigManager getInstance() {
+        if (instance == null) {         // thread A and B both see null
+            instance = new ConfigManager(); // both create an instance — BUG
+        }
+        return instance;
+    }
+}
+```
+
+**Incorrect (broken double-checked locking without volatile):**
+
+```java
+public class DatabasePool {
+    private static DatabasePool instance; // missing volatile — broken!
+
+    public static DatabasePool getInstance() {
+        if (instance == null) {
+            synchronized (DatabasePool.class) {
+                if (instance == null) {
+                    instance = new DatabasePool(); // may be visible as partially initialized
+                }
+            }
+        }
+        return instance;
+    }
+}
+```
+
+**Correct (Initialization-on-demand holder idiom — preferred):**
+
+```java
+public class ConfigManager {
+    private ConfigManager() {
+        loadConfiguration();
+    }
+
+    // JVM class loading guarantees thread-safe, lazy initialization
+    private static final class Holder {
+        private static final ConfigManager INSTANCE = new ConfigManager();
+    }
+
+    public static ConfigManager getInstance() {
+        return Holder.INSTANCE;
+    }
+}
+```
+
+**Correct (double-checked locking with volatile — acceptable):**
+
+```java
+public class DatabasePool {
+    private static volatile DatabasePool instance; // volatile is required
+
+    private DatabasePool() {}
+
+    public static DatabasePool getInstance() {
+        if (instance == null) {
+            synchronized (DatabasePool.class) {
+                if (instance == null) {
+                    instance = new DatabasePool();
+                }
+            }
+        }
+        return instance;
+    }
+}
+```
+
+**Correct (enum singleton — simplest and safest):**
+
+```java
+// Enum singletons are thread-safe by JVM specification and handle serialization correctly
+public enum AppConfig {
+    INSTANCE;
+
+    private final String dbUrl;
+
+    AppConfig() {
+        dbUrl = System.getenv("DB_URL");
+    }
+
+    public String getDbUrl() {
+        return dbUrl;
+    }
+}
+
+// Usage:
+AppConfig.INSTANCE.getDbUrl();
+```
+
+**Preferred approaches (in order):**
+1. **Enum singleton** — safest, handles serialization automatically
+2. **Initialization-on-demand holder** — lazy, thread-safe, no synchronization overhead
+3. **Double-checked locking with `volatile`** — acceptable for legacy code
+4. **Spring `@Component` / `@Service`** — let the DI container manage lifecycle (best for application code)
+
+**Tools:** PMD (`NonThreadSafeSingleton`, `DoubleCheckedLocking`), FindBugs/SpotBugs (`DC_DOUBLECHECK`, `ST_WRITE_TO_STATIC_FROM_INSTANCE_METHOD`), SonarQube (`S2168`)

package/skill-assets/sunlint-code-quality/rules/java/J009-utility-class-constructor.md

@@ -0,0 +1,82 @@
+---
+title: Utility Classes Must Have a Private Constructor
+impact: LOW
+impactDescription: utility classes with public or default constructors can be accidentally instantiated, wasting memory and exposing confusing API
+tags: design, best-practice, java, clean-code
+---
+
+## Utility Classes Must Have a Private Constructor
+
+A **utility class** is a class that consists only of `static` methods and/or constants — it is never meant to be instantiated (e.g., `java.util.Collections`, `java.util.Arrays`, `Math`). Without a private constructor, a utility class:
+- Can be instantiated by mistake, creating useless objects.
+- May confuse callers about whether an instance has state.
+- May be accidentally extended, inheriting a public constructor.
+
+**Incorrect:**
+
+```java
+// No constructor — Java adds a public default constructor automatically
+public class StringUtils {
+    public static String capitalize(String s) { ... }
+    public static boolean isBlank(String s) { ... }
+}
+
+// Default-visibility constructor — package-accessible
+public class MathUtils {
+    MathUtils() {} // package-private, should be private
+    public static int add(int a, int b) { return a + b; }
+}
+
+// Can be instantiated:
+StringUtils utils = new StringUtils(); // meaningless object
+```
+
+**Correct:**
+
+```java
+public final class StringUtils { // final prevents subclassing
+    private StringUtils() {
+        // Utility class — do not instantiate
+        throw new UnsupportedOperationException("Utility class cannot be instantiated");
+    }
+
+    public static String capitalize(String s) {
+        if (s == null || s.isEmpty()) return s;
+        return Character.toUpperCase(s.charAt(0)) + s.substring(1).toLowerCase();
+    }
+
+    public static boolean isBlank(String s) {
+        return s == null || s.trim().isEmpty();
+    }
+}
+
+public final class DateUtils {
+    private DateUtils() {
+        throw new UnsupportedOperationException("Utility class");
+    }
+
+    public static LocalDate parseDate(String date) {
+        return LocalDate.parse(date, DateTimeFormatter.ISO_LOCAL_DATE);
+    }
+}
+```
+
+**Using Lombok `@UtilityClass`:**
+
+```java
+import lombok.experimental.UtilityClass;
+
+@UtilityClass // auto-generates private constructor + throws exception + makes class final
+public class ValidationUtils {
+    public boolean isValidEmail(String email) {
+        return email != null && email.matches("^[\\w.-]+@[\\w.-]+\\.[a-zA-Z]{2,}$");
+    }
+}
+```
+
+**Conditions for a utility class:**
+- All methods are `static`
+- No instance fields (or only `static final` constants)
+- The class is not designed as a base class
+
+**Tools:** Checkstyle (`HideUtilityClassConstructor`), PMD (`UseUtilityClass`), SonarQube (`S1118`)

package/skill-assets/sunlint-code-quality/rules/java/J010-preserve-stack-trace.md

@@ -0,0 +1,119 @@
+---
+title: Preserve Stack Trace When Rethrowing Exceptions
+impact: HIGH
+impactDescription: discarding the original exception's stack trace makes debugging nearly impossible — the root cause is permanently lost
+tags: error-handling, best-practice, java, debugging
+---
+
+## Preserve Stack Trace When Rethrowing Exceptions
+
+When catching an exception and throwing a new one, always pass the original exception as the **cause**. If you only rethrow a new exception with `e.getMessage()` or no cause at all, the original stack trace — which shows where the error actually originated — is permanently discarded.
+
+**Incorrect (losing the stack trace):**
+
+```java
+public void processOrder(Order order) throws OrderException {
+    try {
+        paymentService.charge(order.getPayment());
+    } catch (PaymentException e) {
+        // Message-only: root cause stack trace is lost
+        throw new OrderException("Payment failed: " + e.getMessage());
+    }
+}
+
+public User loadUser(Long id) throws ServiceException {
+    try {
+        return userRepository.findById(id).orElseThrow();
+    } catch (Exception e) {
+        // No cause: impossible to trace back to the original error
+        throw new ServiceException("User not found");
+    }
+}
+
+public void sendEmail(String to, String body) {
+    try {
+        emailClient.send(to, body);
+    } catch (EmailException e) {
+        logger.error("Email failed");  // No exception logged — stack trace lost
+        throw new RuntimeException("Email failed"); // No cause chained
+    }
+}
+```
+
+**Correct (preserving the stack trace):**
+
+```java
+public void processOrder(Order order) throws OrderException {
+    try {
+        paymentService.charge(order.getPayment());
+    } catch (PaymentException e) {
+        // Pass the original exception as the cause
+        throw new OrderException("Payment failed for orderId=" + order.getId(), e);
+    }
+}
+
+public User loadUser(Long id) throws ServiceException {
+    try {
+        return userRepository.findById(id)
+            .orElseThrow(() -> new UserNotFoundException("User not found: id=" + id));
+    } catch (UserNotFoundException e) {
+        throw new ServiceException("User lookup failed: id=" + id, e); // chained
+    }
+}
+
+public void sendEmail(String to, String body) {
+    try {
+        emailClient.send(to, body);
+    } catch (EmailException e) {
+        logger.error("Email sending failed: recipient={}", to, e); // log with cause
+        throw new NotificationException("Email failed", e);        // chain the cause
+    }
+}
+```
+
+**Using initCause for exceptions without cause constructors:**
+
+```java
+try {
+    someOperation();
+} catch (SomeException e) {
+    RuntimeException wrapped = new RuntimeException("Operation failed");
+    wrapped.initCause(e); // alternative to constructor argument
+    throw wrapped;
+}
+```
+
+**Inspecting cause chains:**
+
+```java
+// Cause chain is accessible at runtime
+try {
+    processOrder(order);
+} catch (OrderException e) {
+    Throwable cause = e.getCause(); // retrieves PaymentException
+    logger.error("Root cause: {}", cause.getMessage());
+}
+```
+
+**Adding suppressed exceptions (try-with-resources pattern):**
+
+```java
+// When closing a resource also throws — use addSuppressed
+Exception primary = null;
+try {
+    doWork();
+} catch (Exception e) {
+    primary = e;
+    throw e;
+} finally {
+    try {
+        resource.close();
+    } catch (Exception closeEx) {
+        if (primary != null) {
+            primary.addSuppressed(closeEx); // preserves both
+        }
+    }
+}
+```
+
+**Tools:** PMD (`PreserveStackTrace`), SpotBugs (`REC_CATCH_EXCEPTION`), SonarQube (`S1166`)

package/skill-assets/sunlint-code-quality/rules/java/J011-null-safe-compare.md

@@ -0,0 +1,88 @@
+---
+title: Put Literals First in String Comparisons to Avoid NullPointerException
+impact: MEDIUM
+impactDescription: variable.equals("literal") throws NPE if variable is null; reversing operands makes comparisons null-safe without extra null checks
+tags: null-safety, best-practice, java, error-prone
+---
+
+## Put Literals First in String Comparisons to Avoid NullPointerException
+
+When comparing a string variable to a known literal value, placing the literal on the **left** side of `.equals()` prevents a `NullPointerException` if the variable is `null`. Since a string literal is never `null`, calling `.equals()` on it is always safe.
+
+**Incorrect (variable first — may throw NPE):**
+
+```java
+public boolean isActive(String status) {
+    return status.equals("ACTIVE"); // NPE if status is null
+}
+
+public void handleRequest(HttpServletRequest request) {
+    String method = request.getMethod();
+    if (method.equals("POST")) {    // NPE if method is null (unlikely but possible)
+        processPost();
+    }
+}
+
+public boolean checkRole(User user) {
+    String role = user.getRole();       // getRole() might return null
+    return role.equals("ADMIN");        // NPE
+}
+```
+
+**Correct (literal first — null-safe):**
+
+```java
+public boolean isActive(String status) {
+    return "ACTIVE".equals(status); // returns false if status is null — no NPE
+}
+
+public void handleRequest(HttpServletRequest request) {
+    String method = request.getMethod();
+    if ("POST".equals(method)) {    // safe even if method is null
+        processPost();
+    }
+}
+
+public boolean checkRole(User user) {
+    String role = user.getRole();
+    return "ADMIN".equals(role);    // null-safe
+}
+
+// Also applies to equalsIgnoreCase:
+public boolean isAdminIgnoreCase(String role) {
+    return "admin".equalsIgnoreCase(role); // null-safe
+}
+
+// Constant comparison:
+public static final String DEFAULT_LANG = "en";
+
+public boolean isDefaultLanguage(String lang) {
+    return DEFAULT_LANG.equals(lang); // constant on left — same principle
+}
+```
+
+**When to use Objects.equals() instead:**
+
+Use `Objects.equals(a, b)` when **both** values may be `null` and you want a symmetric comparison:
+
+```java
+// Objects.equals handles both nulls:
+boolean same = Objects.equals(user.getRole(), adminRole); // null-safe on both sides
+
+// Equivalent to:
+// user.getRole() == adminRole || (user.getRole() != null && user.getRole().equals(adminRole))
+```
+
+**compareTo / compareToIgnoreCase:**
+
+Note that reversing the literal changes the sign of the result:
+
+```java
+// Original:  x.compareTo("bar") > 0
+// Reversed: "bar".compareTo(x) < 0  ← sign flipped!
+
+// Be careful when converting compareTo usage
+if ("bar".compareTo(x) < 0) { ... } // equivalent to x.compareTo("bar") > 0
+```
+
+**Tools:** PMD (`LiteralsFirstInComparisons`), SonarQube (`S1132`), IntelliJ Inspections

package/skill-assets/sunlint-code-quality/rules/java/J012-use-enum-collections.md

@@ -0,0 +1,104 @@
+---
+title: Use EnumSet and EnumMap for Enum Keys
+impact: MEDIUM
+impactDescription: EnumSet and EnumMap use array-backed implementations that are significantly faster and more memory-efficient than HashSet/HashMap for enum keys
+tags: performance, best-practice, java, collections
+---
+
+## Use EnumSet and EnumMap for Enum Keys
+
+When working with collections whose elements or keys are enum values, `EnumSet` and `EnumMap` should be preferred over `HashSet` and `HashMap`. They use a compact array-backed representation internally — bit vectors for `EnumSet` and an array indexed by ordinal for `EnumMap` — providing better performance and less memory usage.
+
+**Incorrect (using general-purpose collections with enum keys):**
+
+```java
+public enum Permission { READ, WRITE, DELETE, ADMIN }
+
+public class User {
+    // Using HashSet for enum values — wastes memory, slower
+    private Set<Permission> permissions = new HashSet<>();
+
+    public boolean hasPermission(Permission p) {
+        return permissions.contains(p); // HashSet lookup — unnecessary overhead
+    }
+}
+
+public class RolePolicy {
+    // Using HashMap for enum keys — suboptimal
+    private Map<Permission, String> descriptions = new HashMap<>();
+
+    public void setupDescriptions() {
+        descriptions.put(Permission.READ, "Can read resources");
+        descriptions.put(Permission.WRITE, "Can write resources");
+        descriptions.put(Permission.ADMIN, "Full access");
+    }
+}
+```
+
+**Correct (using EnumSet / EnumMap):**
+
+```java
+import java.util.EnumSet;
+import java.util.EnumMap;
+
+public enum Permission { READ, WRITE, DELETE, ADMIN }
+
+public class User {
+    // EnumSet: compact bit-vector implementation, O(1) operations
+    private Set<Permission> permissions = EnumSet.noneOf(Permission.class);
+
+    public void grantPermission(Permission p) {
+        permissions.add(p);
+    }
+
+    public boolean hasPermission(Permission p) {
+        return permissions.contains(p);
+    }
+}
+
+public class RolePolicy {
+    // EnumMap: array-backed, indexed by enum ordinal
+    private Map<Permission, String> descriptions = new EnumMap<>(Permission.class);
+
+    public void setupDescriptions() {
+        descriptions.put(Permission.READ, "Can read resources");
+        descriptions.put(Permission.WRITE, "Can write resources");
+        descriptions.put(Permission.ADMIN, "Full access");
+    }
+}
+```
+
+**EnumSet factory methods:**
+
+```java
+// Empty set
+Set<Permission> none = EnumSet.noneOf(Permission.class);
+
+// All values
+Set<Permission> all = EnumSet.allOf(Permission.class);
+
+// Specific values
+Set<Permission> readOnly = EnumSet.of(Permission.READ);
+
+// Range (by ordinal order)
+Set<Permission> basic = EnumSet.range(Permission.READ, Permission.WRITE);
+
+// Complement
+Set<Permission> nonAdmin = EnumSet.complementOf(EnumSet.of(Permission.ADMIN));
+```
+
+**Performance comparison:**
+
+| Operation | HashSet | EnumSet |
+|-----------|---------|---------|
+| `add` | O(1) avg | O(1) bit op |
+| `contains` | O(1) avg | O(1) bit op |
+| Memory | ~40 bytes/entry | 1 bit/entry |
+| Iteration | Hash order | Enum ordinal order |
+
+**When to apply:**
+- Use `EnumSet` whenever you have a `Set<SomeEnum>`
+- Use `EnumMap` whenever you have a `Map<SomeEnum, V>`
+- Both are drop-in replacements that implement `Set` and `Map` respectively
+
+**Tools:** PMD (`UseEnumCollections`), IntelliJ Inspections

package/skill-assets/sunlint-code-quality/rules/java/J013-return-empty-not-null.md

@@ -0,0 +1,102 @@
+---
+title: Return Empty Collection Instead of null
+impact: MEDIUM
+impactDescription: returning null for collections forces every caller to perform a null check, causing NullPointerExceptions when they forget
+tags: null-safety, design, java, clean-code
+---
+
+## Return Empty Collection Instead of null
+
+Methods that return collections (`List`, `Set`, `Map`, arrays) should **never** return `null` to indicate "no results." Instead, return an empty collection. This eliminates the need for null checks on every call site, reduces potential `NullPointerException` bugs, and makes the API safer and more predictable.
+
+This principle is described in *Effective Java* by Joshua Bloch: *"Never return null in place of an empty array or collection."*
+
+**Incorrect (returning null):**
+
+```java
+public List<Order> getOrdersByUser(Long userId) {
+    List<Order> orders = orderRepository.findByUserId(userId);
+    if (orders.isEmpty()) {
+        return null; // forces callers to null-check
+    }
+    return orders;
+}
+
+public String[] getTagsForPost(Long postId) {
+    String[] tags = tagRepository.findByPost(postId);
+    if (tags == null || tags.length == 0) {
+        return null; // callers must check for null before iterating
+    }
+    return tags;
+}
+
+// Callers must remember to null-check — easy to forget:
+List<Order> orders = orderService.getOrdersByUser(userId);
+for (Order order : orders) { // NPE if orders is null
+    processOrder(order);
+}
+```
+
+**Correct (returning empty collections):**
+
+```java
+import java.util.Collections;
+import java.util.List;
+
+public List<Order> getOrdersByUser(Long userId) {
+    List<Order> orders = orderRepository.findByUserId(userId);
+    if (orders == null || orders.isEmpty()) {
+        return Collections.emptyList(); // immutable, no allocation overhead
+    }
+    return orders;
+}
+
+// Or with Stream API:
+public List<Order> getOrdersByUser(Long userId) {
+    return orderRepository.findByUserId(userId) != null
+        ? orderRepository.findByUserId(userId)
+        : Collections.emptyList();
+}
+
+// Using List.of() (Java 9+):
+public List<String> getTagsForPost(Long postId) {
+    List<String> tags = tagRepository.findByPost(postId);
+    return tags != null ? tags : List.of(); // immutable empty list
+}
+
+// Arrays:
+public String[] getPermissionsForRole(String role) {
+    String[] perms = permissionRepo.findByRole(role);
+    return perms != null ? perms : new String[0]; // empty array, not null
+}
+
+// Callers now iterate safely without null checks:
+List<Order> orders = orderService.getOrdersByUser(userId);
+for (Order order : orders) { // safe — at worst iterates 0 times
+    processOrder(order);
+}
+```
+
+**Preferred empty collection factories:**
+
+| Type | Factory |
+|------|---------|
+| `List<T>` | `Collections.emptyList()` or `List.of()` (Java 9+) |
+| `Set<T>` | `Collections.emptySet()` or `Set.of()` |
+| `Map<K,V>` | `Collections.emptyMap()` or `Map.of()` |
+| `T[]` | `new T[0]` |
+
+**Note:** `Collections.emptyList()`, `emptySet()`, and `emptyMap()` return immutable, singleton instances — no memory allocation per call. They are the most efficient choice.
+
+**Exception — when null has semantic meaning:**
+If `null` and "empty" are **intentionally different states** (e.g., "not loaded yet" vs "loaded but empty"), `Optional<List<T>>` or a domain wrapper class should be used instead of `null`.
+
+```java
+// Distinguish "not configured" from "configured but empty"
+public Optional<List<String>> getWhitelist(String service) {
+    if (!config.hasWhitelist(service)) return Optional.empty();
+    return Optional.of(config.getWhitelist(service));
+}
+```
+
+**Tools:** PMD (`ReturnEmptyCollectionRatherThanNull`), SonarQube (`S1168`), IntelliJ Inspections