@sun-asterisk/sunlint 1.3.47 → 1.3.49

package/skill-assets/sunlint-code-quality/rules/java/J004-use-java-time.md

@@ -0,0 +1,91 @@
+---
+title: Use java.time Instead of Legacy Date and Calendar
+impact: MEDIUM
+impactDescription: java.util.Date and Calendar are mutable, thread-unsafe, and poorly designed; java.time provides a modern, immutable, thread-safe API
+tags: best-practice, java, modernization, thread-safety
+---
+
+## Use java.time Instead of Legacy Date and Calendar
+
+`java.util.Date` and `java.util.Calendar` were introduced in Java 1.0 and 1.1 respectively. They are mutable (not thread-safe), have confusing APIs (months are 0-indexed in `Calendar`), and are generally considered a design failure. Since Java 8, the `java.time` package (JSR-310) provides a comprehensive, immutable, thread-safe date/time API.
+
+**Incorrect (using legacy Date/Calendar):**
+
+```java
+import java.util.Date;
+import java.util.Calendar;
+
+public class OrderService {
+    public Date calculateDeliveryDate(Date orderDate, int days) {
+        Calendar cal = Calendar.getInstance();
+        cal.setTime(orderDate);
+        cal.add(Calendar.DAY_OF_MONTH, days); // Calendar.DAY_OF_MONTH is error-prone
+        return cal.getTime(); // mutable — caller can modify the returned value
+    }
+
+    public boolean isExpired(Date expiryDate) {
+        return new Date().after(expiryDate); // new Date() for "now" is verbose
+    }
+
+    // Storing timestamps
+    private Date createdAt = new Date(); // mutable — bad for records
+}
+```
+
+**Correct (using java.time):**
+
+```java
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.time.ZonedDateTime;
+import java.time.ZoneId;
+import java.time.Instant;
+import java.time.Duration;
+
+public class OrderService {
+    public LocalDate calculateDeliveryDate(LocalDate orderDate, int days) {
+        return orderDate.plusDays(days); // fluent, immutable, clear
+    }
+
+    public boolean isExpired(LocalDateTime expiryDateTime) {
+        return LocalDateTime.now().isAfter(expiryDateTime);
+    }
+
+    // Storing timestamps
+    private final Instant createdAt = Instant.now(); // immutable
+
+    // Working with timezones
+    public ZonedDateTime getOrderTimeInJST(Instant instant) {
+        return instant.atZone(ZoneId.of("Asia/Tokyo"));
+    }
+
+    // Duration/period calculation
+    public long getDaysUntilDeadline(LocalDate deadline) {
+        return Duration.between(
+            LocalDate.now().atStartOfDay(),
+            deadline.atStartOfDay()
+        ).toDays();
+    }
+}
+```
+
+**Migration guide:**
+
+| Legacy | java.time replacement |
+|--------|----------------------|
+| `java.util.Date` | `java.time.Instant` (for UTC timestamps) |
+| `java.util.Calendar` | `java.time.ZonedDateTime` |
+| `java.sql.Date` | `java.time.LocalDate` |
+| `java.sql.Timestamp` | `java.time.LocalDateTime` or `Instant` |
+| `SimpleDateFormat` | `java.time.format.DateTimeFormatter` |
+
+**Key types in java.time:**
+- `LocalDate` — date without time/timezone (e.g., 2024-01-15)
+- `LocalTime` — time without date/timezone
+- `LocalDateTime` — date + time, no timezone
+- `ZonedDateTime` — date + time + timezone
+- `Instant` — a Unix timestamp (UTC)
+- `Duration` — time-based amount (seconds, nanoseconds)
+- `Period` — date-based amount (years, months, days)
+
+**Tools:** PMD (`ReplaceJavaUtilDate`, `ReplaceJavaUtilCalendar`), SonarQube (`S2143`)

package/skill-assets/sunlint-code-quality/rules/java/J005-no-print-stack-trace.md

@@ -0,0 +1,80 @@
+---
+title: Do Not Use printStackTrace(); Use a Logger
+impact: MEDIUM
+impactDescription: printStackTrace() outputs to stderr, cannot be controlled by log configuration, and may expose sensitive stack traces in production
+tags: logging, best-practice, java, security
+---
+
+## Do Not Use printStackTrace(); Use a Logger
+
+`e.printStackTrace()` writes directly to `System.err` — it bypasses the logging framework entirely, cannot be filtered, redirected, or formatted by log configuration, and in production environments the output may be lost or may expose sensitive internal details (class names, method names, library versions) to attackers.
+
+**Incorrect (using printStackTrace):**
+
+```java
+public void processPayment(Payment payment) {
+    try {
+        paymentGateway.charge(payment);
+    } catch (PaymentException e) {
+        e.printStackTrace(); // writes to System.err — uncontrolled output
+    }
+}
+
+public User findUser(Long id) {
+    try {
+        return userRepository.findById(id).orElseThrow();
+    } catch (Exception e) {
+        e.printStackTrace(); // loses structured logging, no context
+        return null;
+    }
+}
+```
+
+**Correct (using a logger):**
+
+```java
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+public class PaymentService {
+    private static final Logger logger = LoggerFactory.getLogger(PaymentService.class);
+
+    public void processPayment(Payment payment) {
+        try {
+            paymentGateway.charge(payment);
+        } catch (PaymentException e) {
+            // Log at ERROR with context AND the exception (includes stack trace in log output)
+            logger.error("Payment failed for orderId={}, amount={}",
+                payment.getOrderId(), payment.getAmount(), e);
+            throw new PaymentProcessingException("Payment failed", e);
+        }
+    }
+
+    public User findUser(Long id) {
+        try {
+            return userRepository.findById(id)
+                .orElseThrow(() -> new UserNotFoundException("User not found: " + id));
+        } catch (UserNotFoundException e) {
+            logger.warn("User lookup failed: userId={}", id, e);
+            throw e;
+        }
+    }
+}
+```
+
+**Differences between logging levels for exceptions:**
+
+```java
+// ERROR: unexpected, system-level failure, requires immediate attention
+logger.error("Database connection lost", e);
+
+// WARN: recoverable error, degraded functionality
+logger.warn("Payment gateway timeout, retrying: orderId={}", orderId, e);
+
+// INFO: expected business exception (user not found, validation fail)
+logger.info("Login attempt failed: username={}", username, e);
+```
+
+**Passing the exception as the last argument** to SLF4J/Logback/Log4j2 automatically appends a full stack trace to the log entry — equivalent to calling `printStackTrace()` but through the proper logging pipeline.
+
+**Tools:** PMD (`AvoidPrintStackTrace`), SonarQube (`S1148`), SpotBugs

package/skill-assets/sunlint-code-quality/rules/java/J006-no-system-println.md

@@ -0,0 +1,89 @@
+---
+title: Do Not Use System.out.println in Production Code
+impact: MEDIUM
+impactDescription: System.out/err output bypasses logging configuration, cannot be disabled without code changes, and may leak sensitive data
+tags: logging, best-practice, java, production
+---
+
+## Do Not Use System.out.println in Production Code
+
+`System.out.println` and `System.err.println` write directly to standard output/error streams. In production:
+- They cannot be filtered, leveled, or structured.
+- They cannot be turned off without changing code and redeploying.
+- They do not carry context (timestamp, thread, class name) unless added manually.
+- Output may be lost in containerized or cloud environments.
+- They may print sensitive data (credentials, PII) in server logs.
+
+**Incorrect:**
+
+```java
+public class AuthService {
+    public User authenticate(String username, String password) {
+        System.out.println("Authenticating user: " + username);  // logs PII
+        System.out.println("password = " + password);            // SECURITY RISK
+        try {
+            User user = userRepository.findByUsername(username);
+            System.out.println("User found: " + user.getEmail()); // PII leak
+            return user;
+        } catch (Exception e) {
+            System.err.println("Auth failed: " + e.getMessage()); // unstructured
+            return null;
+        }
+    }
+}
+
+public class DataProcessor {
+    public void process(List<Order> orders) {
+        System.out.println("Processing " + orders.size() + " orders"); // no structured log
+        for (Order order : orders) {
+            System.out.println("Order: " + order); // cannot be filtered
+        }
+    }
+}
+```
+
+**Correct (using SLF4J/Logback):**
+
+```java
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+public class AuthService {
+    private static final Logger logger = LoggerFactory.getLogger(AuthService.class);
+
+    public User authenticate(String username, String password) {
+        logger.debug("Authenticating user: username={}", username);
+        // Never log the password
+        try {
+            User user = userRepository.findByUsername(username);
+            logger.info("Authentication successful: userId={}", user.getId());
+            return user;
+        } catch (UserNotFoundException e) {
+            logger.warn("Authentication failed: username={}", username);
+            throw e;
+        }
+    }
+}
+
+public class DataProcessor {
+    private static final Logger logger = LoggerFactory.getLogger(DataProcessor.class);
+
+    public void process(List<Order> orders) {
+        logger.info("Starting order processing: count={}", orders.size());
+        for (Order order : orders) {
+            logger.debug("Processing order: orderId={}", order.getId());
+        }
+        logger.info("Order processing complete: count={}", orders.size());
+    }
+}
+```
+
+**Exception for tests and scripts:**
+
+`System.out.println` is acceptable only in:
+- `main()` methods of CLI tools and standalone scripts
+- Unit test setup code (though test frameworks' reporters are better)
+
+Mark these with a `@SuppressWarnings("PMD.SystemPrintln")` annotation if needed.
+
+**Tools:** PMD (`SystemPrintln`), SonarQube (`S106`), Checkstyle

package/skill-assets/sunlint-code-quality/rules/java/J007-proper-logger.md

@@ -0,0 +1,91 @@
+---
+title: Logger Must Be private static final
+impact: MEDIUM
+impactDescription: improper logger declaration can cause memory leaks, serialization issues, and incorrect class attribution in log output
+tags: logging, best-practice, java, naming
+---
+
+## Logger Must Be private static final
+
+A logger field should always be declared as `private static final` and named after the class it belongs to. This ensures:
+- **`private`**: Not accessible from outside the class, encapsulated properly.
+- **`static`**: Shared across all instances — not re-created per object, avoiding memory overhead.
+- **`final`**: Cannot be reassigned — prevents accidental reassignment.
+- **Named with the correct class**: Ensures log entries display the correct source class.
+
+**Incorrect:**
+
+```java
+// Not static — a new logger is created for every object instance
+public class OrderService {
+    private final Logger logger = LoggerFactory.getLogger(OrderService.class); // bad: not static
+}
+
+// Not private — accessible from outside
+public class UserService {
+    public static final Logger LOGGER = LoggerFactory.getLogger(UserService.class); // bad: public
+}
+
+// Wrong class name — log entries will show wrong class
+public class PaymentService {
+    private static final Logger logger = LoggerFactory.getLogger(OrderService.class); // bad: wrong class
+}
+
+// Using java.util.logging without naming it LOG or logger consistently
+public class ReportService {
+    private static Logger l = Logger.getLogger("reports"); // bad: name "l" is vague; string name is wrong
+}
+```
+
+**Correct:**
+
+```java
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+public class OrderService {
+    private static final Logger logger = LoggerFactory.getLogger(OrderService.class);
+
+    public void createOrder(Order order) {
+        logger.info("Creating order: orderId={}", order.getId());
+    }
+}
+
+// For java.util.logging (standard library):
+import java.util.logging.Logger;
+
+public class ReportService {
+    private static final Logger logger = Logger.getLogger(ReportService.class.getName());
+}
+
+// For Log4j 2:
+import org.apache.logging.log4j.Logger;
+import org.apache.logging.log4j.LogManager;
+
+public class NotificationService {
+    private static final Logger logger = LogManager.getLogger(NotificationService.class);
+}
+
+// With Lombok @Slf4j annotation (auto-generates private static final logger):
+import lombok.extern.slf4j.Slf4j;
+
+@Slf4j
+public class InventoryService {
+    public void checkStock(Long productId) {
+        log.info("Checking stock: productId={}", productId); // 'log' is auto-generated
+    }
+}
+```
+
+**Standard conventions:**
+- Variable name: `logger` (preferred) or `log` (common with Lombok)
+- Avoid `LOG`, `LOGGER` (all-caps suggests a compile-time constant, loggers are runtime objects)
+- Always pass the owning class literal: `LoggerFactory.getLogger(MyClass.class)`
+
+**Frameworks supported:**
+- SLF4J + Logback (recommended)
+- Log4j 2
+- `java.util.logging` (JUL, standard library)
+- Lombok `@Slf4j`, `@Log4j2`, `@CommonsLog`
+
+**Tools:** PMD (`ProperLogger`), SonarQube (`S1312`), IntelliJ Inspections

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`)