@sun-asterisk/sunlint 1.3.39 → 1.3.41

package/skill-assets/sunlint-code-quality/rules/go/C022-no-unused-variables.md

@@ -0,0 +1,34 @@
+---
+title: No Unused Variables
+impact: LOW
+impactDescription: reduces codebase noise and potential bugs
+tags: variables, cleanup, quality
+---
+
+## No Unused Variables
+
+Unused variables clutter the code and often indicate a bug (missing logic). Go compiler strictly enforces this for local variables.
+
+**Incorrect (unused variables):**
+
+```go
+func Calculate(a, b int) int {
+	result := a + b
+	temp := result * 2 // UNUSED
+	
+	return result
+}
+```
+
+**Correct (clean code):**
+
+```go
+func Calculate(a, b int) int {
+	return a + b
+}
+
+// If a variable is needed for its side effect but the value is not, use _
+_, err := os.Open("file.txt")
+```
+
+**Tools:** Go Compiler, `go vet`, GolangCI-Lint (unused)

package/skill-assets/sunlint-code-quality/rules/go/C023-no-duplicate-names.md

@@ -0,0 +1,41 @@
+---
+title: No Variable Shadowing
+impact: HIGH
+impactDescription: prevents subtle bugs where inner variables hide outer ones
+tags: variables, shadowing, scope, quality
+---
+
+## No Variable Shadowing
+
+Variable shadowing occurs when a variable declared within a certain scope has the same name as a variable in an outer scope. This can lead to subtle and hard-to-debug logic errors.
+
+**Incorrect (shadowed variables):**
+
+```go
+func processItems(items []string) {
+    user := "admin"
+
+    for _, item := range items {
+        user := findUser(item) // Shadowing outer 'user' with := 
+        fmt.Println("Processing for user:", user)
+    }
+
+    // Outer 'user' is still "admin", which might be unexpected if the loop 
+    // was intended to update it.
+}
+```
+
+**Correct (unique names or explicit assignment):**
+
+```go
+func processItems(items []string) {
+    globalUser := "admin"
+
+    for _, item := range items {
+        currentUser := findUser(item)
+        fmt.Println("Processing for user:", currentUser)
+    }
+}
+```
+
+**Tools:** `go vet -shadow`, GolangCI-Lint (shadow)

package/skill-assets/sunlint-code-quality/rules/go/C024-centralize-constants.md

@@ -0,0 +1,55 @@
+---
+title: Centralize Constants
+impact: HIGH
+impactDescription: makes values easy to find and update
+tags: constants, magic-numbers, configuration, quality
+---
+
+## Centralize Constants
+
+Magic numbers or strings scattered throughout the code are hard to find and update. Centralizing them improves maintainability.
+
+**Incorrect (magic numbers/strings):**
+
+```go
+func ValidateUser(password string) bool {
+	if len(password) < 8 {
+		return false
+	}
+	return true
+}
+
+func (s *Service) Retry() {
+	for i := 0; i < 3; i++ {
+		// retry logic
+	}
+}
+```
+
+**Correct (centralized constants):**
+
+```go
+package constants
+
+const (
+	MaxRetryAttempts   = 3
+	MinPasswordLength  = 8
+	DefaultTimeoutSecs = 30
+)
+
+const (
+	StatusPending = iota
+	StatusApproved
+	StatusCancelled
+)
+
+// Usage
+if len(password) < constants.MinPasswordLength { ... }
+```
+
+**Benefits:**
+- Single source of truth
+- Self-documenting
+- Easy to update across the entire codebase
+
+**Tools:** GolangCI-Lint (gocritic, gomnd), Code Review

package/skill-assets/sunlint-code-quality/rules/go/C029-catch-log-root-cause.md

@@ -0,0 +1,56 @@
+---
+title: All Error Handling Must Log Root Cause
+impact: HIGH
+impactDescription: enables debugging and incident response
+tags: error-handling, logging, debugging, observability, quality
+---
+
+## All Error Handling Must Log Root Cause
+
+Silent failures make debugging impossible. Without proper logging, you cannot trace issues in production.
+
+**Incorrect (silent or minimal logging):**
+
+```go
+func processPayment(order order.Order) {
+    err := paymentGateway.Charge(order)
+    if err != nil {
+        // Silent failure!
+        return
+    }
+}
+
+func saveUser(user *User) error {
+    if err := db.Save(user); err != nil {
+        return nil // No logging, no context
+    }
+    return nil
+}
+```
+
+**Correct (comprehensive error logging/wrapping):**
+
+```go
+func processPayment(ctx context.Context, order order.Order) error {
+    if err := paymentGateway.Charge(order); err != nil {
+        slog.Error("payment processing failed",
+            "order_id", order.ID,
+            "user_id", order.UserID,
+            "amount", order.Amount,
+            "error", err,
+            "request_id", ctx.Value("request_id"),
+        )
+        return fmt.Errorf("charging order %s: %w", order.ID, err)
+    }
+    return nil
+}
+```
+
+**Log context should include:**
+- Error message (and stack trace if available)
+- Relevant entity IDs (order, user, etc.)
+- Request/correlation ID
+- Input that caused the error
+- Timing information
+
+**Tools:** GolangCI-Lint, PR review, `slog`

package/skill-assets/sunlint-code-quality/rules/go/C030-custom-error-classes.md

@@ -0,0 +1,69 @@
+---
+title: Use Custom Error Types
+impact: HIGH
+impactDescription: enables proper error categorization and handling
+tags: error-handling, custom-errors, patterns, quality
+---
+
+## Use Custom Error Types
+
+Custom error types enable proper error handling, categorization, and monitoring. They provide clear contracts for API consumers.
+
+**Incorrect (generic errors):**
+
+```go
+return errors.New("user not found")
+return errors.New("invalid input")
+return errors.New("database connection failed")
+```
+
+**Correct (custom error structs):**
+
+```go
+// Base application error type can be useful but Go often uses simple structs
+type AppError struct {
+    Code       string
+    Message    string
+    StatusCode int
+    Context    map[string]any
+}
+
+func (e *AppError) Error() string {
+    return e.Message
+}
+
+// Specific errors
+type UserNotFoundError struct {
+    UserID string
+}
+
+func (e UserNotFoundError) Error() string {
+    return fmt.Sprintf("user %s not found", e.UserID)
+}
+
+type ValidationError struct {
+    Field   string
+    Message string
+}
+
+func (e ValidationError) Error() string {
+    return fmt.Sprintf("validation error on %s: %s", e.Field, e.Message)
+}
+
+// Usage
+return UserNotFoundError{UserID: "123"}
+return ValidationError{Field: "email", Message: "invalid format"}
+
+// Handling
+if errors.As(err, &UserNotFoundError{}) {
+    // handle 404
+}
+```
+
+**Benefits:**
+- Type-safe error handling using `errors.As`
+- Automatic HTTP status mapping
+- Structured error context
+- Consistent error format
+
+**Tools:** GolangCI-Lint, Code Convention

package/skill-assets/sunlint-code-quality/rules/go/C033-separate-data-access.md

@@ -0,0 +1,68 @@
+---
+title: Separate Processing And Data Access
+impact: HIGH
+impactDescription: enables testable business logic
+tags: separation, repository, service, architecture, quality
+---
+
+## Separate Processing And Data Access
+
+Mixing business logic with database queries creates tight coupling and makes testing require real databases.
+
+**Incorrect (mixed concerns):**
+
+```go
+type OrderService struct {
+    db *sql.DB
+}
+
+func (s *OrderService) CalculateDiscount(userId string) (int, error) {
+    // Business logic mixed with data access
+    var isPremium bool
+    db.QueryRow("SELECT is_premium FROM users WHERE id = ?", userId).Scan(&isPremium)
+    
+    var orderCount int
+    db.QueryRow("SELECT count(*) FROM orders WHERE user_id = ?", userId).Scan(&orderCount)
+    
+    discount := 0
+    if orderCount > 10 { discount += 5 }
+    if isPremium { discount += 10 }
+    
+    return discount, nil
+}
+```
+
+**Correct (separated layers):**
+
+```go
+// Repository - data access only
+type UserRepository interface {
+    FindByID(id string) (*User, error)
+}
+
+type OrderRepository interface {
+    CountByUserID(id string) (int, error)
+}
+
+// Service - business logic only
+type DiscountService struct {
+    userRepo  UserRepository
+    orderRepo OrderRepository
+}
+
+func (s *DiscountService) CalculateDiscount(userId string) (int, error) {
+    user, _ := s.userRepo.FindByID(userId)
+    count, _ := s.orderRepo.CountByUserID(userId)
+    
+    return s.computeDiscount(user, count), nil
+}
+
+func (s *DiscountService) computeDiscount(user *User, orderCount int) int {
+    discount := 0
+    if orderCount > 10 { discount += 5 }
+    if user != nil && user.IsPremium { discount += 10 }
+    return discount
+}
+```
+
+**Tools:** Architectural review, Code Review

package/skill-assets/sunlint-code-quality/rules/go/C035-error-context-logging.md

@@ -0,0 +1,48 @@
+---
+title: Log All Relevant Context On Errors
+impact: HIGH
+impactDescription: enables quick debugging and incident response
+tags: error-handling, logging, context, debugging, quality
+---
+
+## Log All Relevant Context On Errors
+
+Context-rich logs enable quick debugging. Without proper context, finding root causes is difficult.
+
+**Incorrect (minimal context):**
+
+```go
+slog.Error("error occurred")
+slog.Error(err.Error())
+```
+
+**Correct (comprehensive context using slog):**
+
+```go
+slog.Error("failed to process order",
+  // What happened
+  "error", err,
+  "stack", string(debug.Stack()), // Optional: but useful for critical errors
+  
+  // Context
+  "order_id", order.ID,
+  "user_id", user.ID,
+  "request_id", ctx.Value("request_id"),
+  
+  // Input that caused the issue
+  "item_count", len(order.Items),
+  "total_amount", order.Total,
+  
+  // Timing
+  "processing_time_ms", time.Since(startTime).Milliseconds(),
+)
+```
+
+**Essential context:**
+- Error details
+- Entity identifiers
+- Request/correlation IDs
+- Relevant input summary
+- Timing information
+
+**Tools:** `slog`, `zap`, `logback` equivalent

package/skill-assets/sunlint-code-quality/rules/go/C041-no-hardcoded-secrets.md

@@ -0,0 +1,45 @@
+---
+title: No Hardcoded Secrets In Repo
+impact: HIGH
+impactDescription: prevents credential exposure
+tags: secrets, credentials, security, git, quality
+---
+
+## No Hardcoded Secrets In Repo
+
+Secrets in code are exposed to everyone with repo access and can be scraped by attackers.
+
+**Incorrect (secrets in code):**
+
+```go
+const APIKey = "sk-abc123xyz789"
+const DBPassword = "admin123"
+
+func init() {
+    client := stripe.NewClient("sk_live_xxx")
+}
+```
+
+**Correct (environment/secrets manager):**
+
+```go
+// From environment
+apiKey := os.Getenv("API_KEY")
+
+// From secrets manager
+apiKey, err := secretManager.GetSecret(ctx, "stripe-api-key")
+
+// Validation at startup
+if os.Getenv("API_KEY") == "" {
+    log.Fatal("API_KEY environment variable is required")
+}
+```
+
+```gitignore
+# .gitignore
+.env
+*.pem
+*.key
+```
+
+**Tools:** GitLeaks, TruffleHog, pre-commit hooks

package/skill-assets/sunlint-code-quality/rules/go/C042-boolean-naming.md

@@ -0,0 +1,42 @@
+---
+title: Boolean Names Is/Has/Should
+impact: HIGH
+impactDescription: makes conditions instantly readable
+tags: naming, booleans, readability, quality
+---
+
+## Boolean Names Is/Has/Should
+
+Boolean prefixes make conditions instantly readable.
+
+**Incorrect (unclear boolean names):**
+
+```go
+active := user.Status == "active"
+admin := checkAdminRole(user)
+items := len(cart) > 0
+update := needsRefresh()
+```
+
+**Correct (boolean prefixes):**
+
+```go
+isActive := user.Status == "active"
+isAdmin := checkAdminRole(user)
+hasItems := len(cart) > 0
+shouldUpdate := needsRefresh()
+canEdit := hasPermission(user, "edit")
+willExpire := expirationDate.Before(time.Now())
+```
+
+**Boolean prefixes:**
+
+| Prefix | Use For |
+|--------|---------|
+| `Is` | State (IsActive, IsEnabled) |
+| `Has` | Ownership (HasPermission, HasError) |
+| `Should` | Decision (ShouldUpdate, ShouldRetry) |
+| `Can` | Capability (CanEdit, CanDelete) |
+| `Will` | Future (WillExpire, WillRetry) |
+
+**Tools:** Linter, Code Review

package/skill-assets/sunlint-code-quality/rules/go/C052-controller-parsing.md

@@ -0,0 +1,62 @@
+---
+title: Separate Parsing From Handlers
+impact: HIGH
+impactDescription: keeps handlers thin and focused
+tags: handler, parsing, transformation, patterns, quality
+---
+
+## Separate Parsing From Handlers
+
+Handlers (controllers) should be thin - only handling HTTP concerns. Transformation logic should be extracted.
+
+**Incorrect (transformation in handler):**
+
+```go
+func GetUserHandler(w http.ResponseWriter, r *http.Request) {
+    user, _ := userService.FindByID(r.URL.Query().Get("id"))
+    
+    // Transformation logic in handler
+    response := map[string]any{
+        "id":        user.ID,
+        "full_name": user.FirstName + " " + user.LastName,
+        "email":     strings.ToLower(user.Email),
+        "created_at": user.CreatedAt.Format("2006-01-02"),
+    }
+    
+    json.NewEncoder(w).Encode(response)
+}
+```
+
+**Correct (separate mapper/DTO):**
+
+```go
+type UserResponse struct {
+    ID        string `json:"id"`
+    FullName  string `json:"full_name"`
+    Email     string `json:"email"`
+    CreatedAt string `json:"created_at"`
+}
+
+func ToUserResponse(user *User) UserResponse {
+    return UserResponse{
+        ID:        user.ID,
+        FullName:  user.FirstName + " " + user.LastName,
+        Email:     strings.ToLower(user.Email),
+        CreatedAt: user.CreatedAt.Format("2006-01-02"),
+    }
+}
+
+// Clean handler
+func GetUserHandler(w http.ResponseWriter, r *http.Request) {
+    user, _ := userService.FindByID(r.URL.Query().Get("id"))
+    json.NewEncoder(w).Encode(ToUserResponse(user))
+}
+```
+
+**Benefits:**
+- Reusable transformation logic
+- Testable mappers
+- Clean handlers
+- Consistent response format
+
+**Tools:** Code review, Architecture rules

package/skill-assets/sunlint-code-quality/rules/go/C060-superclass-logic.md

@@ -0,0 +1,60 @@
+---
+title: Do Not Ignore Embedded Struct Logic
+impact: HIGH
+impactDescription: ensures proper composition behavior
+tags: composition, embedding, override, quality
+---
+
+## Do Not Ignore Embedded Struct Logic
+
+When "overriding" methods of an embedded struct, ensure the embedded behavior is preserved unless explicitly intended otherwise.
+
+**Incorrect (ignoring embedded logic):**
+
+```go
+type BaseService struct{}
+
+func (s *BaseService) Save(entity any) error {
+    s.Validate(entity)
+    s.BeforeSave(entity)
+    // ... actual save logic ...
+    return nil
+}
+
+type UserService struct {
+    BaseService
+}
+
+func (s *UserService) Save(user any) error {
+    // Completely ignores BaseService.Save logic (validation, hooks, etc.)
+    return s.repo.Save(user)
+}
+```
+
+**Correct (explicitly calling embedded method):**
+
+```go
+type UserService struct {
+    BaseService
+}
+
+func (s *UserService) Save(user *User) error {
+    // Add user-specific preprocessing
+    user.UpdatedAt = time.Now()
+    
+    // Call embedded struct implementation
+    if err := s.BaseService.Save(user); err != nil {
+        return err
+    }
+    
+    // Add user-specific postprocessing
+    return s.updateSearchIndex(user)
+}
+```
+
+**When to skip:**
+- Complete replacement is intentional
+- Base implementation doesn't apply
+- Document the reason clearly
+
+**Tools:** Static Analysis, Code Review

package/skill-assets/sunlint-code-quality/rules/go/C067-no-hardcoded-config.md

@@ -0,0 +1,51 @@
+---
+title: Do Not Hardcode Configuration
+impact: HIGH
+impactDescription: enables environment-specific deployments
+tags: configuration, environment, deployment, quality
+---
+
+## Do Not Hardcode Configuration
+
+Hardcoded configuration requires code changes to deploy to different environments.
+
+**Incorrect (hardcoded config):**
+
+```go
+const APIUrl = "https://api.production.example.com"
+const Timeout = 5000
+const MaxFileSize = 10485760
+```
+
+**Correct (externalized config):**
+
+```go
+type Config struct {
+    API struct {
+        URL     string
+        Timeout time.Duration
+    }
+    Upload struct {
+        MaxFileSize int64
+    }
+}
+
+func LoadConfig() *Config {
+    return &Config{
+        API: struct {
+            URL     string
+            Timeout time.Duration
+        }{
+            URL:     getEnv("API_URL", "http://localhost:3000"),
+            Timeout: time.Duration(getEnvInt("API_TIMEOUT", 5000)) * time.Millisecond,
+        },
+        // ...
+    }
+}
+
+// Usage
+cfg := LoadConfig()
+client := &http.Client{Timeout: cfg.API.Timeout}
+```
+
+**Tools:** `os.Getenv`, `viper`, `clever-env`, Manual review