@sun-asterisk/sunlint 1.3.47 → 1.3.49

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

@@ -0,0 +1,108 @@
+---
+title: Do Not Hardcode Configuration
+impact: HIGH
+impactDescription: enables environment-specific deployments
+tags: configuration, environment, deployment, quality
+---
+
+## Do Not Hardcode Configuration
+
+Hardcoded config requires code changes to deploy to different environments.
+
+**Incorrect (hardcoded config):**
+
+```dart
+const apiUrl = 'https://api.production.example.com';
+const timeout = 5000;
+const maxFileSize = 10485760;
+const enableAnalytics = true;
+```
+
+**Correct (externalized config via dart-define):**
+
+```dart
+// lib/config/app_config.dart
+class AppConfig {
+  AppConfig._();
+
+  static const String apiUrl = String.fromEnvironment(
+    'API_URL',
+    defaultValue: 'https://api.dev.example.com',
+  );
+
+  static const int timeoutMs = int.fromEnvironment(
+    'TIMEOUT_MS',
+    defaultValue: 5000,
+  );
+
+  static const int maxFileSizeBytes = int.fromEnvironment(
+    'MAX_FILE_SIZE',
+    defaultValue: 10 * 1024 * 1024, // 10MB
+  );
+
+  static const bool enableAnalytics = bool.fromEnvironment(
+    'ENABLE_ANALYTICS',
+    defaultValue: false,
+  );
+}
+
+// Usage
+final client = HttpClient(baseUrl: AppConfig.apiUrl, timeout: Duration(milliseconds: AppConfig.timeoutMs));
+```
+
+**Build with environment config:**
+
+```bash
+# Development
+flutter run --dart-define=API_URL=https://api.dev.example.com --dart-define=ENABLE_ANALYTICS=false
+
+# Production
+flutter build apk --dart-define=API_URL=https://api.production.example.com --dart-define=ENABLE_ANALYTICS=true
+
+# Using a JSON config file (flutter_launcher_icons approach)
+flutter run --dart-define-from-file=config/dev.json
+flutter build apk --dart-define-from-file=config/prod.json
+```
+
+**Example config files:**
+
+```json
+// config/dev.json
+{
+  "API_URL": "https://api.dev.example.com",
+  "ENABLE_ANALYTICS": "false",
+  "TIMEOUT_MS": "10000"
+}
+```
+
+```json
+// config/prod.json
+{
+  "API_URL": "https://api.production.example.com",
+  "ENABLE_ANALYTICS": "true",
+  "TIMEOUT_MS": "5000"
+}
+```
+
+**For flavor-based config:**
+
+```dart
+// lib/config/flavors.dart
+enum Flavor { dev, staging, production }
+
+class FlavorConfig {
+  static Flavor? _flavor;
+
+  static void initialize(Flavor flavor) {
+    _flavor = flavor;
+  }
+
+  static String get apiUrl => switch (_flavor!) {
+    Flavor.dev => 'https://api.dev.example.com',
+    Flavor.staging => 'https://api.staging.example.com',
+    Flavor.production => 'https://api.example.com',
+  };
+}
+```
+
+**Tools:** dart-define, envied, flutter_flavor, Code Review

package/skill-assets/sunlint-code-quality/rules/go/G001-explicit-error-handling.md

@@ -0,0 +1,53 @@
+---
+title: Explicit Error Handling
+impact: CRITICAL
+impactDescription: prevents silent failures and ensures robust error recovery
+tags: go, error-handling, quality
+---
+
+## Explicit Error Handling
+
+In Go, errors are values and must be handled explicitly. Ignoring errors using `_` or failing to check them leads to unpredictable state and silent failures.
+
+**Incorrect (ignoring errors):**
+
+```go
+func processData(data string) {
+    file, _ := os.Open("config.json") // Error ignored
+    defer file.Close()
+    
+    bytes, _ := io.ReadAll(file) // Error ignored
+    json.Unmarshal(bytes, &config) // Error ignored
+}
+```
+
+**Correct (explicit checking):**
+
+```go
+func processData(data string) error {
+    file, err := os.Open("config.json")
+    if err != nil {
+        return fmt.Errorf("failed to open config: %w", err)
+    }
+    defer file.Close()
+    
+    bytes, err := io.ReadAll(file)
+    if err != nil {
+        return fmt.Errorf("failed to read config: %w", err)
+    }
+    
+    if err := json.Unmarshal(bytes, &config); err != nil {
+        return fmt.Errorf("failed to parse config: %w", err)
+    }
+    
+    return nil
+}
+```
+
+**Benefits:**
+- Prevents silent crashes and data corruption
+- Provides clear trace of what went wrong
+- Forces developers to think about failure paths
+- Makes code easier to debug
+
+**Tools:** errcheck, golangci-lint, staticcheck

package/skill-assets/sunlint-code-quality/rules/go/G002-context-first-argument.md

@@ -0,0 +1,44 @@
+---
+title: Context as First Argument
+impact: MEDIUM
+impactDescription: follows Go idiomatic patterns for cancellation and timeouts
+tags: go, context, patterns, quality
+---
+
+## Context as First Argument
+
+`context.Context` should always be the first parameter of a function, typically named `ctx`. This consistency makes it easy to propagate cancellation, deadlines, and markers across call stacks.
+
+**Incorrect (wrong order or missing):**
+
+```go
+func (s *Service) FetchUser(userID string, ctx context.Context) (*User, error) {
+    // ctx is second argument
+    return s.repo.Get(ctx, userID)
+}
+
+func ProcessTask(taskID string) {
+    // Missing context for potentially long-running operation
+    db.Exec("UPDATE tasks SET status = 'done' WHERE id = ?", taskID)
+}
+```
+
+**Correct (context first):**
+
+```go
+func (s *Service) FetchUser(ctx context.Context, userID string) (*User, error) {
+    return s.repo.Get(ctx, userID)
+}
+
+func ProcessTask(ctx context.Context, taskID string) error {
+    return db.ExecContext(ctx, "UPDATE tasks SET status = 'done' WHERE id = ?", taskID)
+}
+```
+
+**Benefits:**
+- Standardizes API signatures across the codebase
+- Simplifies cancellation propagation
+- Enables proper timeout handling for I/O and external calls
+- Improves observability with trace IDs in context
+
+**Tools:** golangci-lint, contextcheck

package/skill-assets/sunlint-code-quality/rules/go/G003-receiver-consistency.md

@@ -0,0 +1,38 @@
+---
+title: Consistent Receiver Naming
+impact: LOW
+impactDescription: improves readability and consistency
+tags: go, style, quality
+---
+
+## Consistent Receiver Naming
+
+Receiver names should be short (1-2 letters) and consistent across all methods of a type. Do not use generic names like `this`, `self`, or `me`.
+
+**Incorrect (inconsistent or verbose):**
+
+```go
+func (this *UserRepository) Get(id string) (*User, error) { ... }
+
+func (repo *UserRepository) List() ([]*User, error) { ... }
+
+func (self *UserRepository) Update(u *User) error { ... }
+```
+
+**Correct (short and consistent):**
+
+```go
+// Use 'r' consistently for UserRepository
+func (r *UserRepository) Get(id string) (*User, error) { ... }
+
+func (r *UserRepository) List() ([]*User, error) { ... }
+
+func (r *UserRepository) Update(u *User) error { ... }
+```
+
+**Benefits:**
+- Reduces visual noise in method definitions
+- Follows Go community standards
+- Makes it easier to search and scan methods of the same type
+
+**Tools:** golangci-lint, stylecheck

package/skill-assets/sunlint-code-quality/rules/go/G004-avoid-panic.md

@@ -0,0 +1,49 @@
+---
+title: Avoid Panic in Production
+impact: HIGH
+impactDescription: prevents application crashes and enables graceful degradation
+tags: go, error-handling, stability, quality
+---
+
+## Avoid Panic in Production
+
+Panic should be reserved for truly unrecoverable programmer errors (e.g., initialization failure where the app cannot start). Business logic and normal I/O should always use `error` returns.
+
+**Incorrect (panic for normal errors):**
+
+```go
+func GetUser(id string) *User {
+    user, err := db.Find(id)
+    if err != nil {
+        panic(err) // Crash!
+    }
+    return user
+}
+```
+
+**Correct (return error):**
+
+```go
+func GetUser(id string) (*User, error) {
+    user, err := db.Find(id)
+    if err != nil {
+        return nil, fmt.Errorf("failed to find user: %w", err)
+    }
+    return user, nil
+}
+
+// In main or init, panic is acceptable if the app MUST die
+func main() {
+    config, err := LoadConfig()
+    if err != nil {
+        panic("critical config missing: " + err.Error())
+    }
+}
+```
+
+**Benefits:**
+- Improves application uptime and reliability
+- Allows handlers to recover and return HTTP 500 instead of crashing the process
+- Makes the code more predictable and testable
+
+**Tools:** golangci-lint, staticcheck

package/skill-assets/sunlint-code-quality/rules/go/G005-goroutine-leak-prevention.md

@@ -0,0 +1,49 @@
+---
+title: Goroutine Leak Prevention
+impact: HIGH
+impactDescription: prevents memory exhaustion and zombie processes
+tags: go, concurrency, stability, quality
+---
+
+## Goroutine Leak Prevention
+
+Always ensure that a goroutine has a clear termination path, typically via a `context.Context` or a close channel. Goroutines that block indefinitely on channel operations or I/O without a timeout cause memory leaks.
+
+**Incorrect (leaky goroutine):**
+
+```go
+func StartWatcher(ch chan string) {
+    go func() {
+        for msg := range ch { // Blocks forever if ch is never closed
+            fmt.Println(msg)
+        }
+    }()
+}
+```
+
+**Correct (context-aware goroutine):**
+
+```go
+func StartWatcher(ctx context.Context, ch chan string) {
+    go func() {
+        for {
+            select {
+            case <-ctx.Done():
+                return // Exit cleanly when context is cancelled
+            case msg, ok := <-ch:
+                if !ok {
+                    return // Exit when channel is closed
+                }
+                fmt.Println(msg)
+            }
+        }
+    }()
+}
+```
+
+**Benefits:**
+- Prevents memory leaks and resource exhaustion
+- Ensures clean application shutdown
+- Makes concurrent code more predictable and testable
+
+**Tools:** goleak, golangci-lint

package/skill-assets/sunlint-code-quality/rules/go/G006-interface-consumer-definition.md

@@ -0,0 +1,45 @@
+---
+title: Define Interfaces at Consumer Side
+impact: MEDIUM
+impactDescription: promotes decoupling and simplifies testing
+tags: go, architecture, interfaces, quality
+---
+
+## Define Interfaces at Consumer Side
+
+In Go, interfaces are satisfied implicitly. Do not define interfaces in the same package where the implementation is defined (producer side). Instead, define the interface in the package that requires the dependency (consumer side).
+
+**Incorrect (interface in producer package):**
+
+```go
+// package auth
+type Service interface {
+    Login(user, pass string) (string, error)
+}
+
+type serviceImpl struct { ... }
+func (s *serviceImpl) Login(u, p string) (string, error) { ... }
+```
+
+**Correct (interface in consumer package):**
+
+```go
+// package auth (implementation only)
+type Service struct { ... }
+func (s *Service) Login(u, p string) (string, error) { ... }
+
+// package handler (consumer)
+type AuthProvider interface {
+    Login(user, pass string) (string, error)
+}
+
+func LoginHandler(auth AuthProvider) { ... }
+```
+
+**Benefits:**
+- Prevents package circular dependencies
+- Allows packages to define exactly what they need from a dependency
+- Makes it easier to mock dependencies for unit testing
+- Keeps the system more loosely coupled
+
+**Tools:** Code Review, Architecture rules

package/skill-assets/sunlint-code-quality/rules/go/GN001-gin-binding-validation.md

@@ -0,0 +1,57 @@
+---
+title: Use Gin Binding for Validation
+impact: HIGH
+impactDescription: simplifies input handling and ensures consistent validation
+tags: gin, go, validation, quality
+---
+
+## Use Gin Binding for Validation
+
+Leverage Gin's built-in binding mechanism (`ShouldBindJSON`, `ShouldBindQuery`, etc.) and the `validator` library tags. This centralizes validation logic and keeps handlers clean.
+
+**Incorrect (manual parsing and validation):**
+
+```go
+func CreateUser(c *gin.Context) {
+    var raw map[string]interface{}
+    if err := c.BindJSON(&raw); err != nil {
+        c.JSON(400, gin.H{"error": "invalid json"})
+        return
+    }
+    
+    email, ok := raw["email"].(string)
+    if !ok || email == "" {
+        c.JSON(400, gin.H{"error": "email is required"})
+        return
+    }
+    // ... more manual checks
+}
+```
+
+**Correct (struct binding and tags):**
+
+```go
+type CreateUserRequest struct {
+    Email    string `json:"email" binding:"required,email"`
+    Password string `json:"password" binding:"required,min=8"`
+    Age      int    `json:"age" binding:"gte=18"`
+}
+
+func CreateUser(c *gin.Context) {
+    var req CreateUserRequest
+    if err := c.ShouldBindJSON(&req); err != nil {
+        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+        return
+    }
+    
+    // Process validated request
+}
+```
+
+**Benefits:**
+- Reduces boilerplate code in handlers
+- Declarative validation is easier to read and maintain
+- Automatically handles type conversion (e.g., string to int)
+- Provides standard error messages
+
+**Tools:** Gin, go-playground/validator

package/skill-assets/sunlint-code-quality/rules/go/GN002-gin-error-response.md

@@ -0,0 +1,48 @@
+---
+title: Abort with Status for Errors
+impact: MEDIUM
+impactDescription: ensures middleware chain is interrupted and consistent response is sent
+tags: gin, go, error-handling, quality
+---
+
+## Abort with Status for Errors
+
+When a fatal error occurs in a Gin handler or middleware (e.g., auth failure, validation error), use `c.AbortWithStatusJSON` or `c.Abort()` to stop the execution of subsequent handlers in the chain.
+
+**Incorrect (not aborting or only partial return):**
+
+```go
+func AuthMiddleware(c *gin.Context) {
+    token := c.GetHeader("Authorization")
+    if token == "" {
+        c.JSON(401, gin.H{"error": "unauthorized"})
+        // MISSING c.Abort()! Subsequent handlers WILL execute.
+        return 
+    }
+}
+```
+
+**Correct (using AbortWithStatusJSON):**
+
+```go
+func AuthMiddleware(c *gin.Context) {
+    if c.GetHeader("Authorization") == "" {
+        c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "unauthorized"})
+        return
+    }
+}
+
+func Handler(c *gin.Context) {
+    if err := someFunc(); err != nil {
+        c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{"error": "internal error"})
+        return
+    }
+}
+```
+
+**Benefits:**
+- Prevents security bypasses in middleware
+- Consistent error response pattern
+- Guarantees that only one response is sent to the client
+
+**Tools:** Gin

package/skill-assets/sunlint-code-quality/rules/go/GN003-graceful-shutdown.md

@@ -0,0 +1,57 @@
+---
+title: Implement Graceful Shutdown
+impact: MEDIUM
+impactDescription: prevents data loss and ensures clean connection handling
+tags: gin, go, stability, quality
+---
+
+## Implement Graceful Shutdown
+
+Web servers should handle termination signals (`SIGINT`, `SIGTERM`) to allow inflight requests to finish and to close database connections cleanly. Gin's `Run()` method blocks and doesn't support this out of the box; use `http.Server` instead.
+
+**Incorrect (standard Run):**
+
+```go
+func main() {
+    r := gin.Default()
+    r.GET("/", handler)
+    r.Run(":8080") // Blocks and dies immediately on CTRL+C
+}
+```
+
+**Correct (graceful shutdown):**
+
+```go
+func main() {
+    router := gin.Default()
+    srv := &http.Server{
+        Addr:    ":8080",
+        Handler: router,
+    }
+
+    go func() {
+        if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+            log.Fatalf("listen: %s\n", err)
+        }
+    }()
+
+    // Wait for interrupt signal
+    quit := make(chan os.Signal, 1)
+    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
+    <-quit
+
+    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+    defer cancel()
+    
+    if err := srv.Shutdown(ctx); err != nil {
+        log.Fatal("Server Shutdown:", err)
+    }
+}
+```
+
+**Benefits:**
+- Prevents dropping active user connections
+- Allows finishing long-running database transactions
+- Ensures monitoring tools report clean shutdown instead of "crash"
+
+**Tools:** Go Standard Library, Gin

package/skill-assets/sunlint-code-quality/rules/go/GN004-gin-route-logical-grouping.md

@@ -0,0 +1,54 @@
+---
+title: Logical Route Grouping
+impact: MEDIUM
+impactDescription: improves code organization and shared middleware management
+tags: gin, go, routing, quality
+---
+
+## Logical Route Grouping
+
+Use `RouterGroup` to organize routes logically (e.g., by version, resource, or access level). This allows applying middleware (like auth or logging) to a specific group of routes without repetition.
+
+**Incorrect (flat and repetitive):**
+
+```go
+func RegisterRoutes(r *gin.Engine) {
+    r.GET("/api/v1/users", AuthMiddleware(), GetUsers)
+    r.POST("/api/v1/users", AuthMiddleware(), CreateUser)
+    r.GET("/api/v1/users/:id", AuthMiddleware(), GetUser)
+    r.GET("/health", HealthCheck)
+}
+```
+
+**Correct (logical grouping):**
+
+```go
+func RegisterRoutes(r *gin.Engine) {
+    // Public routes
+    r.GET("/health", HealthCheck)
+    
+    // API v1 group
+    v1 := r.Group("/api/v1")
+    {
+        // Auth required group
+        auth := v1.Group("/")
+        auth.Use(AuthMiddleware())
+        {
+            users := auth.Group("/users")
+            {
+                users.GET("/", GetUsers)
+                users.POST("/", CreateUser)
+                users.GET("/:id", GetUser)
+            }
+        }
+    }
+}
+```
+
+**Benefits:**
+- Reduces code duplication for middleware application
+- Provides clear structure of the API URL space
+- Simplifies refactoring and versioning (e.g., adding `/v2` group)
+- Improves readability of the main routing configuration
+
+**Tools:** Gin