@sun-asterisk/sunlint 1.3.48 → 1.3.49

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

@@ -0,0 +1,91 @@
+---
+title: Do Not Ignore Superclass Logic
+impact: HIGH
+impactDescription: ensures proper inheritance behavior
+tags: inheritance, override, superclass, oop, quality
+---
+
+## Do Not Ignore Superclass Logic
+
+When overriding methods, ensure superclass behavior is preserved unless explicitly intended otherwise. This is especially important in Flutter for `initState`, `dispose`, `build`, and lifecycle methods.
+
+**Incorrect (ignoring superclass):**
+
+```dart
+class BaseRepository {
+  Future<void> save(Entity entity) async {
+    validate(entity);
+    await beforeSave(entity);
+    await database.insert(entity.toMap());
+    await afterSave(entity);
+  }
+}
+
+class UserRepository extends BaseRepository {
+  @override
+  Future<void> save(User user) async {
+    // Completely ignores validation, hooks, etc.
+    await database.insert(user.toMap());
+  }
+}
+```
+
+**Correct (calling super):**
+
+```dart
+class UserRepository extends BaseRepository {
+  @override
+  Future<void> save(User user) async {
+    // Add user-specific preprocessing
+    user = user.copyWith(updatedAt: DateTime.now());
+
+    // Call superclass implementation
+    await super.save(user);
+
+    // Add user-specific postprocessing
+    await updateSearchIndex(user);
+  }
+}
+```
+
+**Flutter lifecycle - always call super at correct position:**
+
+```dart
+// initState: super FIRST
+@override
+void initState() {
+  super.initState(); // Must be first
+  _controller = AnimationController(vsync: this);
+}
+
+// dispose: super LAST
+@override
+void dispose() {
+  _controller.dispose(); // Clean up first
+  super.dispose(); // Must be last
+}
+
+// didChangeDependencies: super FIRST
+@override
+void didChangeDependencies() {
+  super.didChangeDependencies();
+  _theme = Theme.of(context);
+}
+```
+
+**When to intentionally skip super:**
+
+```dart
+class UserRepository extends BaseRepository {
+  /// Override: users require special serialization,
+  /// base validation is not applicable for legacy schema.
+  @override
+  Future<void> save(User user) async {
+    await validateUser(user); // Custom validation replaces base
+    // Intentionally not calling super.save()
+    await userTable.upsert(user.toLegacyMap());
+  }
+}
+```
+
+**Tools:** dart_analyzer, Code Review, flutter_lints

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-gin/AGENTS.md

@@ -0,0 +1,149 @@
+# Go Gin Framework — SunLint Agent Guide
+
+> Priority directives for AI agents working on Go + Gin projects.
+> Rule files: `.agent/skills/sunlint-code-quality/rules/`
+
+---
+
+## Critical Patterns — Apply Every Time
+
+### Middleware Chain Termination
+- After sending a response that should stop the chain → `c.AbortWithStatusJSON(code, body)` then `return`
+- `c.AbortWithStatusJSON` calls `c.Abort()` internally — don't call both
+- Plain `return` from a handler does NOT stop downstream handlers
+- See: `GN001-abort-after-response.md`
+
+### Request Binding + Validation
+- Every `c.ShouldBindJSON(&req)` → must be followed by `if err != nil { c.AbortWithStatusJSON(400, ...); return }`
+- Declare all validation rules as struct `binding:` tags: `binding:"required,email"`, `binding:"min=1,max=255"`
+- **Never** skip the error check from `ShouldBind*`
+- See: `GN003-bind-error-handling.md`, `GN008-struct-validation-tags.md`
+
+### Context Usage
+- Inside handlers: `ctx := c.Request.Context()` — pass to all downstream calls
+- **Never** `context.Background()` inside a handler
+- **Never** pass `*gin.Context` to a goroutine — copy scalar values first, pass `c.Request.Context()`
+- See: `GN002-request-context.md`, `GN010-context-scope.md`
+
+### Do Not Log Sensitive DataTesting commands rõ ràng trong package.json/Makefile
+Standard conventions (eslint, prettier, gofmt đã config sẵn)
+4. Test với agents trước khi commit
+Quy trình recommended:
+
+Bước 1: Tạo baseline
+
+# Chạy agent KHÔNG có AGENTS.md trên vài tasks nhỏ
+# Đo success rate, cost
+
+Bước 2: Thêm AGENTS.md, measure lại
+
+# So sánh với baseline
+# Nếu không improve hoặc cost tăng quá nhiều → bỏ AGENTS.md
+
+Bước 3: Iterate
+
+# Nếu quyết định giữ AGENTS.md, hãy giữ nó concise
+# Monitor agent behavior qua time
+
+5. Monitor Context Length
+Context files nên dưới 500 tokens (t
+- Logging middleware logs only: method, path, status, duration, request_id, client IP
+- **Never** log request bodies, `Authorization` header values, or any field named password/token/card
+- See: `GN012-no-log-sensitive.md`
+
+---
+
+## Architecture Patterns
+
+### Handler struct — dependency injection
+Handlers are structs with injected service interfaces. No globals. No `new(Service)` inside handlers.
+```go
+type OrderHandler struct {
+    service OrderService     // interface — mockable
+    logger  *slog.Logger
+}
+func NewOrderHandler(svc OrderService, logger *slog.Logger) *OrderHandler {
+    return &OrderHandler{service: svc, logger: logger}
+}
+```
+See: `GN004-dependency-injection.md`
+
+### Route organisation
+```go
+r := gin.New()
+r.Use(gin.Recovery(), RequestID(), RequestLogger(logger))   // global
+
+public := r.Group("/api/v1")
+{ /* unauthenticated routes */ }
+
+private := r.Group("/api/v1")
+private.Use(JWTAuth(validator))
+{ /* authenticated routes */ }
+```
+See: `GN005-route-groups-middleware.md`, `GN011-middleware-concerns.md`
+
+### Production setup checklist
+```go
+gin.SetMode(os.Getenv("GIN_MODE"))    // "release" in prod — GN007
+r := gin.New()
+r.Use(CustomRecovery(logger))          // GN009
+r.Use(RequestID())                     // GN011
+r.Use(RequestLogger(logger))           // GN012
+// ... register groups (GN005)
+```
+
+### HTTP Status Codes
+- `POST` success → `c.JSON(http.StatusCreated, obj)` (201)
+- `DELETE` no body → `c.Status(http.StatusNoContent)` (204)
+- Not found → `c.AbortWithStatusJSON(http.StatusNotFound, gin.H{"error": "not found"})` (404)
+- Validation error → `c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{"error": err.Error()})` (400)
+- **Always** use `net/http` constants — never magic integers
+- See: `GN006-http-status-codes.md`
+
+### Cross-cutting concerns
+Auth, rate limiting, CORS, request ID, structured logging → **always middleware**, never inside handlers.
+See: `GN011-middleware-concerns.md`
+
+---
+
+## Run Commands
+
+```bash
+# Development
+go run ./cmd/api/main.go
+GIN_MODE=debug go run ./cmd/api/main.go
+
+# Build
+go build -o bin/api ./cmd/api/
+
+# Test (always with race detector)
+go test -race ./...
+go test -race -run TestOrderHandler ./internal/handlers/
+go test -cover ./...
+
+# Linting
+golangci-lint run ./...
+staticcheck ./...
+
+# Env for production
+GIN_MODE=release
+PORT=8080
+```
+
+---
+
+## What NOT to do (quick reference)
+
+| ❌ Wrong | ✅ Correct |
+|---|---|
+| `return` after `c.JSON` in middleware | `c.AbortWithStatusJSON(...)` then `return` |
+| `context.Background()` in handler | `c.Request.Context()` |
+| `go func() { use c.Get(...) }()` | Copy value before goroutine: `val := c.GetString(...)` |
+| `c.ShouldBindJSON(&req)` without err check | `if err := c.ShouldBindJSON(&req); err != nil { abort }` |
+| Manual `if req.Email == ""` validation | `binding:"required,email"` struct tag |
+| `var db *gorm.DB` package global | Inject `db *gorm.DB` as struct field |
+| Auth check inside handler | `JWTAuth()` middleware on route group |
+| `log.Printf("body: %s", body)` | Log method+path+status+duration only |
+| `gin.Default()` in production | `gin.New()` + explicit `Recovery()` + structured logger |
+| `c.JSON(200, gin.H{"error": ...})` | `c.AbortWithStatusJSON(http.StatusBadRequest, ...)` |
+| `GIN_MODE` not set (debug default) | `GIN_MODE=release` in production environment |

package/skill-assets/sunlint-code-quality/rules/go-gin/GN001-abort-after-response.md

@@ -0,0 +1,75 @@
+---
+title: "GN001 – Call c.Abort() After Terminating in Middleware"
+impact: high
+impactDescription: "Missing c.Abort() causes subsequent middleware handlers and the final route handler to still execute after an early response has been sent, causing duplicate writes and data leaks."
+tags: [go, gin, middleware, correctness]
+---
+
+# GN001 – Call `c.Abort()` After Terminating in Middleware
+
+## Rule
+
+Any middleware that sends a response and intends to stop the chain **must** call `c.Abort()` (or `c.AbortWithStatus()` / `c.AbortWithStatusJSON()`) immediately after writing. Never rely on `return` alone.
+
+## Why
+
+`c.Next()` executes subsequent handlers in sequence. A plain `return` exits the current handler but Gin still runs the remaining handlers in the chain. `c.Abort()` sets the index past all remaining handlers so the chain stops cleanly.
+
+## Wrong
+
+```go
+func AuthMiddleware() gin.HandlerFunc {
+    return func(c *gin.Context) {
+        token := c.GetHeader("Authorization")
+        if token == "" {
+            c.JSON(http.StatusUnauthorized, gin.H{"error": "unauthorized"})
+            return   // ❌ returns from this func but downstream handlers still run
+        }
+        c.Next()
+    }
+}
+
+func RateLimitMiddleware() gin.HandlerFunc {
+    return func(c *gin.Context) {
+        if isRateLimited(c.ClientIP()) {
+            c.JSON(http.StatusTooManyRequests, gin.H{"error": "rate limit exceeded"})
+            // ❌ forgot both return and Abort — next handler fires and writes again
+        }
+        c.Next()
+    }
+}
+```
+
+## Correct
+
+```go
+func AuthMiddleware() gin.HandlerFunc {
+    return func(c *gin.Context) {
+        token := c.GetHeader("Authorization")
+        if token == "" {
+            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "unauthorized"})
+            // c.Abort() is called inside AbortWithStatusJSON — no c.Next() needed
+            return
+        }
+        // validation passes — continue chain
+        c.Set("user_id", parsedUserID)
+        c.Next()
+    }
+}
+
+func RateLimitMiddleware() gin.HandlerFunc {
+    return func(c *gin.Context) {
+        if isRateLimited(c.ClientIP()) {
+            c.AbortWithStatusJSON(http.StatusTooManyRequests, gin.H{"error": "rate limit exceeded"})
+            return
+        }
+        c.Next()
+    }
+}
+```
+
+## Notes
+
+- `c.AbortWithStatus(code)` and `c.AbortWithStatusJSON(code, obj)` both call `c.Abort()` internally — you don't need to call `c.Abort()` separately when using these.
+- After `c.Abort()`, code after the call in the same function still runs — use `return` to exit the function body.
+- Verify with unit tests: register middleware + handler, send a bad request, assert the handler body was NOT executed.

package/skill-assets/sunlint-code-quality/rules/go-gin/GN002-request-context.md

@@ -0,0 +1,64 @@
+---
+title: "GN002 – Use c.Request.Context(), Not context.Background()"
+impact: medium
+impactDescription: "context.Background() ignores client disconnects and request deadlines; c.Request.Context() propagates cancellation automatically."
+tags: [go, gin, context, correctness]
+---
+
+# GN002 – Use `c.Request.Context()` Not `context.Background()`
+
+## Rule
+
+When passing a context to database calls, external HTTP requests, or any `ctx context.Context` parameter inside a Gin handler, always use `c.Request.Context()`. Never create a fresh `context.Background()` inside a handler.
+
+## Why
+
+`c.Request.Context()` is derived from the HTTP request and carries the client's cancellation signal. If the client disconnects mid-request, the context is cancelled and all downstream work (DB queries, gRPC calls) is cancelled too — preventing wasted compute. `context.Background()` is never cancelled and leaks work after the client is gone.
+
+## Wrong
+
+```go
+func (h *OrderHandler) Create(c *gin.Context) {
+    var req CreateOrderRequest
+    if err := c.ShouldBindJSON(&req); err != nil {
+        c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+        return
+    }
+
+    // ❌ context.Background() — ignores client disconnect and server deadlines
+    order, err := h.service.CreateOrder(context.Background(), req)
+    if err != nil {
+        c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+        return
+    }
+    c.JSON(http.StatusCreated, order)
+}
+```
+
+## Correct
+
+```go
+func (h *OrderHandler) Create(c *gin.Context) {
+    var req CreateOrderRequest
+    if err := c.ShouldBindJSON(&req); err != nil {
+        c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+        return
+    }
+
+    // ✅ propagates request lifetime, deadline, and cancellation
+    ctx := c.Request.Context()
+    order, err := h.service.CreateOrder(ctx, req)
+    if err != nil {
+        c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+        return
+    }
+    c.JSON(http.StatusCreated, order)
+}
+```
+
+## Notes
+
+- Extract the context once: `ctx := c.Request.Context()` at the top of the handler body.
+- Do **not** store this context in a struct field — contexts must flow through function arguments.
+- If you need a timeout shorter than the request's own deadline: `ctx, cancel := context.WithTimeout(c.Request.Context(), 5*time.Second); defer cancel()`.
+- See GN010 for the rule about not storing Gin context in goroutines.

package/skill-assets/sunlint-code-quality/rules/go-gin/GN003-bind-error-handling.md

@@ -0,0 +1,70 @@
+---
+title: "GN003 – Always Handle ShouldBindJSON / ShouldBind Errors"
+impact: high
+impactDescription: "Ignoring ShouldBindJSON errors means malformed or missing fields are silently treated as zero values, causing corrupted data writes and bypassed validation."
+tags: [go, gin, validation, correctness]
+---
+
+# GN003 – Always Handle `ShouldBindJSON` / `ShouldBind` Errors
+
+## Rule
+
+Every call to `c.ShouldBindJSON`, `c.ShouldBind`, `c.ShouldBindQuery`, or `c.ShouldBindUri` must be followed by an error check. If the error is non-nil, abort immediately with a `400 Bad Request` response.
+
+## Why
+
+`ShouldBind*` populates the target struct but returns an error for malformed JSON, missing required fields (enforced by `binding:"required"` tags), or type mismatches. Ignoring the error means the handler continues with a partially or incorrectly populated struct, silently writing bad data.
+
+## Wrong
+
+```go
+func (h *UserHandler) Create(c *gin.Context) {
+    var req CreateUserRequest
+    c.ShouldBindJSON(&req)   // ❌ error ignored — continues with zero-value struct fields
+
+    user, err := h.service.CreateUser(c.Request.Context(), req)
+    // ...
+}
+
+// Worse: using BindJSON (panics on error in some versions, logs but doesn't stop)
+func (h *UserHandler) Update(c *gin.Context) {
+    var req UpdateUserRequest
+    c.BindJSON(&req)   // ❌ BindJSON writes 400 header but handler still continues
+    h.service.UpdateUser(c.Request.Context(), req)
+}
+```
+
+## 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"`
+}
+
+func (h *UserHandler) Create(c *gin.Context) {
+    var req CreateUserRequest
+    if err := c.ShouldBindJSON(&req); err != nil {
+        c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{
+            "error":   "invalid request",
+            "details": err.Error(),
+        })
+        return
+    }
+
+    user, err := h.service.CreateUser(c.Request.Context(), req)
+    if err != nil {
+        c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{"error": "creation failed"})
+        return
+    }
+    c.JSON(http.StatusCreated, user)
+}
+```
+
+## Notes
+
+- Prefer `ShouldBind*` over `Bind*` — the `Bind*` family writes a `400` header but doesn't abort the handler, making code flow confusing.
+- Use struct tags: `binding:"required"`, `binding:"email"`, `binding:"min=1,max=255"` to shift validation into the binding layer.
+- For detailed error messages, type-assert the error to `validator.ValidationErrors` and format field names cleanly.
+- See GN008 for struct validation tag conventions.

package/skill-assets/sunlint-code-quality/rules/go-gin/GN004-dependency-injection.md

@@ -0,0 +1,78 @@
+---
+title: "GN004 – Use Dependency Injection, Not Global Variables"
+impact: high
+impactDescription: "Global database connections and service instances in package-level vars are untestable, race-prone, and make initialization order fragile."
+tags: [go, gin, architecture, testing]
+---
+
+# GN004 – Use Dependency Injection, Not Global Variables
+
+## Rule
+
+Database connections, service instances, configuration objects, and HTTP clients must be injected as struct fields into handlers. Never declare them as `var db *gorm.DB` at package level and access them from handler functions.
+
+## Why
+
+Global state:
+- Cannot be replaced with a mock in unit tests.
+- Initialization order is implicit — the global may be `nil` if setup hasn't run.
+- Race conditions when tests share globals.
+
+Dependency injection via struct fields makes dependencies explicit, swappable, and testable.
+
+## Wrong
+
+```go
+// db/db.go — package-level global
+var DB *gorm.DB
+
+func Init() {
+    DB, _ = gorm.Open(...)
+}
+
+// handlers/user.go — accesses global directly
+func GetUser(c *gin.Context) {
+    var user User
+    db.DB.First(&user, c.Param("id"))   // ❌ depends on global initialization order
+    c.JSON(200, user)
+}
+```
+
+## Correct
+
+```go
+// handlers/user_handler.go
+type UserHandler struct {
+    db      *gorm.DB         // injected
+    service UserService      // interface — swappable in tests
+    logger  *slog.Logger
+}
+
+func NewUserHandler(db *gorm.DB, svc UserService, logger *slog.Logger) *UserHandler {
+    return &UserHandler{db: db, service: svc, logger: logger}
+}
+
+func (h *UserHandler) GetUser(c *gin.Context) {
+    ctx := c.Request.Context()
+    user, err := h.service.FindUserByID(ctx, c.Param("id"))
+    if err != nil {
+        c.AbortWithStatusJSON(http.StatusNotFound, gin.H{"error": "not found"})
+        return
+    }
+    c.JSON(http.StatusOK, user)
+}
+
+// main.go — wiring
+db := database.Connect(cfg.DSN)
+userSvc := services.NewUserService(db)
+userHandler := handlers.NewUserHandler(db, userSvc, logger)
+
+r := gin.New()
+r.GET("/users/:id", userHandler.GetUser)
+```
+
+## Notes
+
+- Define service dependencies as Go interfaces so handlers can be unit-tested with mocks without a real DB.
+- Use a DI framework (e.g., `google/wire`, `samber/do`) for large projects to automate wiring.
+- Configuration (`Config` structs) should be loaded once in `main` and injected — never read from `os.Getenv` directly inside handlers.