@sun-asterisk/sunlint 1.3.47 → 1.3.49

package/skill-assets/sunlint-code-quality/rules/go-gin/GN008-struct-validation-tags.md

@@ -0,0 +1,90 @@
+---
+title: "GN008 – Use Struct Validation Binding Tags"
+impact: medium
+impactDescription: "Manual if/else validation in handler code is incomplete, inconsistent, and untested; binding tags enforce validation at the deserialization boundary."
+tags: [go, gin, validation, correctness]
+---
+
+# GN008 – Use Struct Validation Binding Tags
+
+## Rule
+
+Define all input validation rules using `binding:` struct tags on request structs. Do not write manual validation logic in handler functions. Handle binding errors as described in GN003.
+
+## Why
+
+Gin uses the `go-playground/validator` library under the hood for `ShouldBind*`. Struct tags declare constraints once, close to the field, and are validated automatically when binding. Scattered `if req.Age < 18` checks in handlers are often incomplete and inconsistent.
+
+## Wrong
+
+```go
+type CreateUserRequest struct {
+    Name  string `json:"name"`
+    Email string `json:"email"`
+    Age   int    `json:"age"`
+    Role  string `json:"role"`
+}
+
+// Handler with manual validation — verbose, incomplete, inconsistent
+func (h *UserHandler) Create(c *gin.Context) {
+    var req CreateUserRequest
+    c.ShouldBindJSON(&req)
+
+    if req.Name == "" {
+        c.JSON(400, gin.H{"error": "name required"})    // ❌ still runs if bind errored
+        return
+    }
+    if !strings.Contains(req.Email, "@") {               // ❌ incomplete email check
+        c.JSON(400, gin.H{"error": "invalid email"})
+        return
+    }
+    // ❌ forgot to validate Age and Role
+}
+```
+
+## Correct
+
+```go
+type CreateUserRequest struct {
+    Name     string `json:"name"     binding:"required,min=2,max=100"`
+    Email    string `json:"email"    binding:"required,email"`
+    Age      int    `json:"age"      binding:"required,min=18,max=120"`
+    Role     string `json:"role"     binding:"required,oneof=user admin moderator"`
+    Phone    string `json:"phone"    binding:"omitempty,e164"`           // optional but validated if present
+    Website  string `json:"website"  binding:"omitempty,url"`
+}
+
+func (h *UserHandler) Create(c *gin.Context) {
+    var req CreateUserRequest
+    if err := c.ShouldBindJSON(&req); err != nil {
+        c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{
+            "error":   "validation failed",
+            "details": formatValidationErrors(err),   // see note below
+        })
+        return
+    }
+    // req is fully validated here — safe to use
+    user, err := h.service.CreateUser(c.Request.Context(), req)
+    // ...
+}
+```
+
+## Common binding tags
+
+| Tag | Meaning |
+|---|---|
+| `required` | Field must be present and non-zero |
+| `omitempty` | Skip validation if field is absent/zero |
+| `min=N,max=M` | Min/max length for strings, min/max value for numbers |
+| `email` | Valid email address format |
+| `url` | Valid URL |
+| `oneof=a b c` | Value must be one of the listed options |
+| `uuid4` | Valid UUID v4 |
+| `e164` | Valid international phone number |
+| `gt=0` | Greater than 0 (useful for IDs) |
+
+## Notes
+
+- To return human-readable errors, type-assert `err` to `validator.ValidationErrors` and format field names.
+- Custom validators: `binding.Validator.RegisterValidation("custom_rule", myFunc)`.
+- For query parameters: `c.ShouldBindQuery(&req)` with `form:"field" binding:"required"` tags.

package/skill-assets/sunlint-code-quality/rules/go-gin/GN009-recovery-middleware.md

@@ -0,0 +1,68 @@
+---
+title: "GN009 – Add gin.Recovery() Middleware in Production"
+impact: high
+impactDescription: "Without Recovery(), an unhandled panic terminates the goroutine and returns a broken TCP connection or empty response to the client; with it, the server stays up and returns 500."
+tags: [go, gin, reliability, middleware]
+---
+
+# GN009 – Add `gin.Recovery()` Middleware in Production
+
+## Rule
+
+Always include `gin.Recovery()` (or a custom recovery middleware) in the production middleware stack. Use `gin.New()` rather than `gin.Default()` and add middleware explicitly so you control what runs.
+
+## Why
+
+Go panics propagate up the call stack and terminate the goroutine. In a Gin HTTP handler, an unrecovered panic kills the request-handling goroutine and the server returns a broken connection. `gin.Recovery()` catches the panic, logs a stack trace, and returns `500 Internal Server Error`, keeping the server alive.
+
+## Wrong
+
+```go
+func main() {
+    r := gin.New()   // ❌ no Recovery — a panic crashes the goroutine silently
+    r.GET("/users/:id", userHandler.Get)
+    r.Run(":8080")
+}
+
+// gin.Default() adds Logger + Recovery but also adds noise to structured log setups
+r := gin.Default()  // acceptable but not recommended for production structured logging
+```
+
+## Correct
+
+```go
+func main() {
+    gin.SetMode(os.Getenv("GIN_MODE"))  // see GN007
+
+    r := gin.New()
+
+    // Custom structured logger (replace gin.Logger())
+    r.Use(RequestLogger(logger))
+
+    // Recovery — MUST be registered before route handlers
+    r.Use(gin.RecoveryWithWriter(gin.DefaultErrorWriter))
+    // OR a custom recovery that logs stack traces to your logger:
+    r.Use(CustomRecovery(logger))
+
+    registerRoutes(r)
+    r.Run(":" + cfg.Port)
+}
+
+// Custom recovery middleware with structured logging
+func CustomRecovery(logger *slog.Logger) gin.HandlerFunc {
+    return gin.CustomRecoveryWithWriter(gin.DefaultErrorWriter, func(c *gin.Context, recovered any) {
+        logger.Error("panic recovered",
+            slog.Any("error", recovered),
+            slog.String("path", c.Request.URL.Path),
+            slog.String("method", c.Request.Method),
+        )
+        c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{"error": "internal server error"})
+    })
+}
+```
+
+## Notes
+
+- Recovery middleware must be registered **before** route handlers — Gin runs middleware in registration order.
+- Don't expose the panic value or stack trace in the HTTP response — log it server-side only.
+- For observability, send panic events to your error tracker (Sentry, Rollbar) inside the custom recovery handler.

package/skill-assets/sunlint-code-quality/rules/go-gin/GN010-context-scope.md

@@ -0,0 +1,68 @@
+---
+title: "GN010 – Do Not Store gin.Context in Goroutines Beyond the Handler"
+impact: high
+impactDescription: "gin.Context is recycled after the handler returns; storing it in a goroutine creates a data race on pool-recycled memory."
+tags: [go, gin, concurrency, correctness]
+---
+
+# GN010 – Do Not Store `gin.Context` in Goroutines Beyond the Handler
+
+## Rule
+
+Never pass `*gin.Context` to a goroutine that outlives the handler function. Copy the values you need (request data, context) before spawning the goroutine.
+
+## Why
+
+Gin uses `sync.Pool` to reuse `*gin.Context` instances for performance. Once the handler function returns, Gin resets and recycles the context object. A goroutine holding a reference to the old `*gin.Context` now reads from a recycled object used by a completely different request — this is an undetected data race and a source of subtle, hard-to-reproduce bugs.
+
+## Wrong
+
+```go
+func (h *NotificationHandler) Send(c *gin.Context) {
+    var req SendNotificationRequest
+    if err := c.ShouldBindJSON(&req); err != nil {
+        c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+        return
+    }
+
+    // ❌ goroutine holds *gin.Context — races after handler returns
+    go func() {
+        userID := c.GetString("user_id")   // c is already recycled here
+        h.service.Notify(context.Background(), userID, req)
+    }()
+
+    c.JSON(http.StatusAccepted, gin.H{"status": "queued"})
+}
+```
+
+## Correct
+
+```go
+func (h *NotificationHandler) Send(c *gin.Context) {
+    var req SendNotificationRequest
+    if err := c.ShouldBindJSON(&req); err != nil {
+        c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+        return
+    }
+
+    // ✅ Copy values from context BEFORE spawning the goroutine
+    userID := c.GetString("user_id")   // copy string value
+    ctx := c.Request.Context()         // copy the stdlib context (safe to pass to goroutine)
+
+    go func() {
+        // Use copied values — no reference to *gin.Context
+        if err := h.service.Notify(ctx, userID, req); err != nil {
+            h.logger.Error("notification failed", slog.String("user_id", userID), slog.Any("error", err))
+        }
+    }()
+
+    c.JSON(http.StatusAccepted, gin.H{"status": "queued"})
+}
+```
+
+## Notes
+
+- `c.Request.Context()` is a standard `context.Context` backed by the HTTP request — safe to copy and pass to goroutines.
+- Extract all required values (`c.Param()`, `c.GetHeader()`, `c.Get()`) into local variables before the goroutine.
+- The Go race detector (`go test -race`) will catch this violation in tests if the goroutine runs fast enough — enable it in CI.
+- Prefer `c.Copy()` if you absolutely need a snapshot of the whole context, but this is memory-heavier than copying specific fields.

package/skill-assets/sunlint-code-quality/rules/go-gin/GN011-middleware-concerns.md

@@ -0,0 +1,92 @@
+---
+title: "GN011 – Apply Cross-Cutting Concerns via Middleware"
+impact: medium
+impactDescription: "Duplicating auth checks, rate limiting, or logging inside individual handlers makes enforcement inconsistent and maintenance expensive."
+tags: [go, gin, middleware, architecture]
+---
+
+# GN011 – Apply Cross-Cutting Concerns via Middleware
+
+## Rule
+
+Authentication, authorization, rate limiting, request logging, request ID injection, and CORS must be implemented as Gin middleware functions and applied at the router/group level — not duplicated inside individual handlers.
+
+## Why
+
+When authentication logic lives inside each handler, a single missed handler creates a security gap. Middleware ensures uniform enforcement. It also separates concerns: handlers contain only business logic; infrastructure concerns live in middleware.
+
+## Wrong
+
+```go
+// ❌ Auth duplicated in every handler
+func (h *OrderHandler) List(c *gin.Context) {
+    token := c.GetHeader("Authorization")
+    userID, err := h.auth.ValidateToken(token)
+    if err != nil {
+        c.AbortWithStatusJSON(401, gin.H{"error": "unauthorized"})
+        return
+    }
+    // ... business logic
+}
+
+func (h *OrderHandler) Create(c *gin.Context) {
+    token := c.GetHeader("Authorization")   // ❌ duplicated
+    userID, err := h.auth.ValidateToken(token)
+    // ...
+}
+```
+
+## Correct
+
+```go
+// middleware/auth.go
+func JWTAuth(tokenValidator TokenValidator) gin.HandlerFunc {
+    return func(c *gin.Context) {
+        token := strings.TrimPrefix(c.GetHeader("Authorization"), "Bearer ")
+        claims, err := tokenValidator.Validate(token)
+        if err != nil {
+            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "invalid token"})
+            return
+        }
+        c.Set("user_id", claims.UserID)
+        c.Set("user_role", claims.Role)
+        c.Next()
+    }
+}
+
+// middleware/request_id.go
+func RequestID() gin.HandlerFunc {
+    return func(c *gin.Context) {
+        id := c.GetHeader("X-Request-ID")
+        if id == "" {
+            id = uuid.New().String()
+        }
+        c.Set("request_id", id)
+        c.Header("X-Request-ID", id)
+        c.Next()
+    }
+}
+
+// main.go — applied at group level (see GN005)
+r := gin.New()
+r.Use(gin.Recovery(), RequestID(), StructuredLogger(logger))
+
+api := r.Group("/api/v1")
+api.Use(JWTAuth(tokenValidator))
+api.Use(RateLimit(100, time.Minute))
+
+api.GET("/orders", orderHandler.List)   // auth + rate limit automatically applied
+api.POST("/orders", orderHandler.Create)
+
+// handlers are clean — no auth logic
+func (h *OrderHandler) List(c *gin.Context) {
+    userID := c.GetString("user_id")   // set by middleware
+    // ... just business logic
+}
+```
+
+## Notes
+
+- Middleware should only set values in the context and call `c.Next()` or `c.Abort()` — no response writing for non-auth middleware.
+- Return factory functions (`func JWTAuth(dep Dep) gin.HandlerFunc`) so middleware is injectable and testable.
+- Always document what a middleware sets in the context (e.g. `"user_id"`, `"request_id"`) so handlers know what keys are available.

package/skill-assets/sunlint-code-quality/rules/go-gin/GN012-no-log-sensitive.md

@@ -0,0 +1,84 @@
+---
+title: "GN012 – Do Not Log Request Bodies Containing Sensitive Data"
+impact: high
+impactDescription: "Logging raw request bodies exposes passwords, tokens, credit card numbers, and PII to anyone with log access, violating GDPR, PCI-DSS, and basic security hygiene."
+tags: [go, gin, security, logging]
+---
+
+# GN012 – Do Not Log Request Bodies Containing Sensitive Data
+
+## Rule
+
+Never log the raw HTTP request body. Log only request metadata (method, path, status, duration, request ID). If you must log body fields for debugging, explicitly allowlist safe fields and mask or omit sensitive ones.
+
+## Why
+
+Request bodies for auth endpoints contain passwords. Payment endpoints contain card data. Profile endpoints contain PII. Logging bodies stores this data in plaintext log files, log aggregators, and monitoring tools — where it lives far beyond the request lifetime and is often accessible to many people.
+
+## Wrong
+
+```go
+// ❌ Logging the full request body
+func RequestBodyLogger() gin.HandlerFunc {
+    return func(c *gin.Context) {
+        body, _ := io.ReadAll(c.Request.Body)
+        log.Printf("Request body: %s", body)   // ❌ logs passwords, tokens, PII
+        c.Request.Body = io.NopCloser(bytes.NewBuffer(body))
+        c.Next()
+    }
+}
+
+// ❌ Logging bound request struct directly (may contain passwords)
+func (h *AuthHandler) Login(c *gin.Context) {
+    var req LoginRequest
+    c.ShouldBindJSON(&req)
+    log.Printf("Login attempt: %+v", req)   // ❌ req.Password logged in plaintext
+}
+```
+
+## Correct
+
+```go
+// ✅ Log only safe metadata — never raw body
+func RequestLogger(logger *slog.Logger) gin.HandlerFunc {
+    return func(c *gin.Context) {
+        start := time.Now()
+        c.Next()
+        logger.Info("request",
+            slog.String("method",     c.Request.Method),
+            slog.String("path",       c.Request.URL.Path),
+            slog.Int("status",        c.Writer.Status()),
+            slog.Duration("duration", time.Since(start)),
+            slog.String("ip",         c.ClientIP()),
+            slog.String("request_id", c.GetString("request_id")),
+            // ✅ no body, no headers that might contain auth tokens
+        )
+    }
+}
+
+// ✅ Log only safe fields from struct - never password/token fields
+func (h *AuthHandler) Login(c *gin.Context) {
+    var req LoginRequest
+    if err := c.ShouldBindJSON(&req); err != nil {
+        c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+        return
+    }
+    // ✅ Log only the email, not the password
+    h.logger.Info("login attempt", slog.String("email", req.Email))
+    // ...
+}
+```
+
+## Sensitive fields to never log
+
+- `password`, `password_confirmation`, `current_password`
+- `token`, `access_token`, `refresh_token`, `api_key`, `secret`
+- `card_number`, `cvv`, `expiry`
+- `ssn`, `national_id`, `date_of_birth` (PII)
+- `Authorization` header value
+
+## Notes
+
+- If you need request body logging for debugging, create a separate debug middleware that is only enabled when `GIN_MODE=debug`.
+- Use log scrubbing libraries (e.g., `go-sanitize`) as a last-resort safety net, but don't rely on them — fix the root cause.
+- `c.Request.Header` can contain `Authorization: Bearer <token>` — log header names only, never values.

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