@sun-asterisk/sunlint 1.3.48 → 1.3.49

package/skill-assets/sunlint-code-quality/rules/java/J001-try-with-resources.md

@@ -0,0 +1,86 @@
+---
+title: Always Use try-with-resources for AutoCloseable
+impact: HIGH
+impactDescription: prevents resource leaks by ensuring streams, connections, and other closeable resources are always closed
+tags: resource-management, best-practice, java, error-prone
+---
+
+## Always Use try-with-resources for AutoCloseable
+
+Since Java 7, the `try`-with-resources statement automatically closes any resource that implements `AutoCloseable` or `Closeable`. Using manual `finally` blocks to close resources is verbose, error-prone, and can silently swallow exceptions thrown during close.
+
+**Incorrect (manual finally block):**
+
+```java
+public void readFile(String path) throws IOException {
+    InputStream in = null;
+    try {
+        in = new FileInputStream(path);
+        // process stream
+        int b = in.read();
+    } catch (IOException e) {
+        logger.error("Failed to read file", e);
+        throw e;
+    } finally {
+        if (in != null) {
+            try {
+                in.close(); // exception here swallows the original
+            } catch (IOException ignored) {}
+        }
+    }
+}
+
+public void queryDatabase(Connection conn) throws SQLException {
+    Statement stmt = null;
+    ResultSet rs = null;
+    try {
+        stmt = conn.createStatement();
+        rs = stmt.executeQuery("SELECT * FROM users");
+    } finally {
+        if (rs != null) rs.close();   // may throw, hiding original
+        if (stmt != null) stmt.close();
+    }
+}
+```
+
+**Correct (try-with-resources):**
+
+```java
+public void readFile(String path) throws IOException {
+    try (InputStream in = new FileInputStream(path)) {
+        // process stream
+        int b = in.read();
+    }
+    // in is automatically closed even if an exception occurs
+}
+
+public void queryDatabase(Connection conn) throws SQLException {
+    try (Statement stmt = conn.createStatement();
+         ResultSet rs = stmt.executeQuery("SELECT * FROM users")) {
+        while (rs.next()) {
+            // process results
+        }
+    }
+    // both stmt and rs are closed in reverse declaration order
+}
+
+// Also works with custom AutoCloseable resources
+public void processResource() throws Exception {
+    try (MyService service = new MyService()) {
+        service.execute();
+    }
+}
+```
+
+**Key benefits:**
+- Resources are closed in reverse declaration order, automatically.
+- Original exceptions are never swallowed by close failures (suppressed exceptions).
+- Cleaner, less boilerplate code.
+
+**Resources that must use try-with-resources:**
+- `InputStream` / `OutputStream` / `Reader` / `Writer`
+- `Connection` / `Statement` / `ResultSet` (JDBC)
+- `HttpClient` / `Socket`
+- Any class implementing `AutoCloseable`
+
+**Tools:** PMD (`UseTryWithResources`), SonarQube (`S2093`), IntelliJ Inspections

package/skill-assets/sunlint-code-quality/rules/java/J002-equals-and-hashcode.md

@@ -0,0 +1,88 @@
+---
+title: Override equals() and hashCode() Together
+impact: HIGH
+impactDescription: violating the equals-hashCode contract breaks HashMap, HashSet, and other hash-based collections silently
+tags: correctness, contract, java, error-prone
+---
+
+## Override equals() and hashCode() Together
+
+In Java, `equals()` and `hashCode()` share a contract: objects that are equal (via `equals()`) **must** have the same hash code. If you override one without overriding the other, hash-based collections (`HashMap`, `HashSet`, `Hashtable`) will malfunction — objects may become unreachable or duplicates may appear.
+
+**Incorrect (only overrides equals):**
+
+```java
+public class User {
+    private Long id;
+    private String email;
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (!(o instanceof User)) return false;
+        User user = (User) o;
+        return Objects.equals(id, user.id);
+    }
+    // Missing hashCode! — HashSet will treat two equal Users as different objects
+}
+
+// Result: map.put(user1); map.get(user2) returns null even if user1.equals(user2)
+Set<User> set = new HashSet<>();
+set.add(new User(1L, "a@b.com"));
+set.contains(new User(1L, "a@b.com")); // false! Bug!
+```
+
+**Incorrect (only overrides hashCode):**
+
+```java
+public class Order {
+    private Long id;
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(id);
+    }
+    // Missing equals! — equals uses identity (==) by default
+}
+```
+
+**Correct (both overridden consistently):**
+
+```java
+public class User {
+    private Long id;
+    private String email;
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (!(o instanceof User)) return false;
+        User user = (User) o;
+        return Objects.equals(id, user.id);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(id); // same fields as equals
+    }
+}
+
+// Using records (Java 16+): equals and hashCode are auto-generated
+public record User(Long id, String email) {}
+
+// Using Lombok:
+@EqualsAndHashCode(onlyExplicitlyIncluded = true)
+public class User {
+    @EqualsAndHashCode.Include
+    private Long id;
+    private String email;
+}
+```
+
+**Rules to follow:**
+- Use the **same fields** in both `equals()` and `hashCode()`.
+- Prefer `Objects.equals()` and `Objects.hash()` over manual null checks.
+- Consider using Lombok `@EqualsAndHashCode` or Java Records for value objects.
+- Never include mutable fields in `hashCode()` if the object will be stored in a hash collection.
+
+**Tools:** PMD (`OverrideBothEqualsAndHashcode`), Checkstyle (`EqualsHashCode`), IntelliJ Inspections

package/skill-assets/sunlint-code-quality/rules/java/J003-string-comparison.md

@@ -0,0 +1,72 @@
+---
+title: Use equals() for String and Object Comparison, Not ==
+impact: HIGH
+impactDescription: using == compares references, not values, causing silent bugs that only appear at runtime
+tags: correctness, java, error-prone, string
+---
+
+## Use equals() for String and Object Comparison, Not ==
+
+In Java, `==` checks **reference equality** (are these the same object in memory?). For Strings and other objects, you almost always want **value equality** — use `.equals()`. While string literals may be interned (sharing references), strings from variables, method returns, or `new String(...)` will have different references, making `==` unreliable.
+
+**Incorrect (using == for string comparison):**
+
+```java
+String status = getStatusFromDatabase(); // returns "ACTIVE"
+if (status == "ACTIVE") {               // BUG: may be false even when value is "ACTIVE"
+    activateUser();
+}
+
+String s1 = new String("hello");
+String s2 = new String("hello");
+if (s1 == s2) {  // always false — different objects
+    // never executed
+}
+
+public boolean isAdmin(String role) {
+    return role == "ADMIN"; // unreliable
+}
+```
+
+**Correct (using equals for string comparison):**
+
+```java
+String status = getStatusFromDatabase();
+if ("ACTIVE".equals(status)) {  // null-safe: won't NPE if status is null
+    activateUser();
+}
+
+// Or with Objects.equals for null-safety on both sides:
+if (Objects.equals(status, "ACTIVE")) {
+    activateUser();
+}
+
+public boolean isAdmin(String role) {
+    return "ADMIN".equals(role);    // preferred: literal first to avoid NPE
+    // or: return role != null && role.equals("ADMIN");
+}
+
+// For enums: use == (enums are singletons, == is correct and preferred)
+if (status == Status.ACTIVE) {  // correct for enums
+    activateUser();
+}
+```
+
+**Literal-first pattern:**
+
+Placing the literal on the left side of `equals()` is a common defensive pattern — if the variable is `null`, the call returns `false` instead of throwing `NullPointerException`:
+
+```java
+// Risky: may throw NPE if name is null
+if (name.equals("John")) { ... }
+
+// Safe: returns false if name is null
+if ("John".equals(name)) { ... }
+```
+
+**Key distinctions:**
+- `String` and all objects: use `.equals()` or `Objects.equals()`
+- `enum` types: use `==` (enums are singleton instances)
+- Primitives (`int`, `boolean`, etc.): use `==`
+
+**Tools:** PMD (`CompareObjectsWithEquals`, `UseEqualsToCompareStrings`), FindBugs/SpotBugs (`ES_COMPARING_STRINGS_WITH_EQ`), IntelliJ Inspections

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