@sun-asterisk/sunlint 1.3.40 → 1.3.42

package/skill-assets/sunlint-code-quality/rules/dart/D017-review-dependencies.md

@@ -0,0 +1,24 @@
+---
+title: Pubspec dependencies should be reviewed regularly
+impact: MEDIUM
+impactDescription: Ensure dependencies are kept up-to-date for security and stability
+tags: maintenance, security, dependencies
+---
+
+## Pubspec dependencies should be reviewed regularly
+
+Dependencies in `pubspec.yaml` should be reviewed and updated regularly (at least every 4 months). Outdated dependencies may contain security vulnerabilities or miss critical performance improvements.
+
+**Incorrect (old lock file):**
+
+```text
+# pubspec.lock last modified: 6 months ago
+```
+
+**Correct (regularly updated):**
+
+```text
+# run 'flutter pub upgrade' and review dependencies regularly
+```
+
+**Tools:** Custom analyzer (D017)

package/skill-assets/sunlint-code-quality/rules/dart/D018-no-commented-code.md

@@ -0,0 +1,34 @@
+---
+title: Remove Commented-Out Code
+impact: LOW
+impactDescription: Keep codebase clean by removing commented-out code
+tags: cleanliness, readability, maintenance
+---
+
+## Remove Commented-Out Code
+
+Commented-out code should be removed instead of being left in the source files. Dead code comments create clutter and confusion. If you need to reference old code, rely on version control (Git).
+
+**Incorrect (abandoned code):**
+
+```dart
+void calculate() {
+  final result = 10 + 5;
+  // print("Debug result: $result");
+  // if (result > 10) {
+  //   doSomething();
+  // }
+  return result;
+}
+```
+
+**Correct (clean file):**
+
+```dart
+void calculate() {
+  final result = 10 + 5;
+  return result;
+}
+```
+
+**Tools:** Custom analyzer (D018)

package/skill-assets/sunlint-code-quality/rules/dart/D019-single-child-wrappers.md

@@ -0,0 +1,31 @@
+---
+title: Avoid Single Child in Multi-Child Widget
+impact: LOW
+impactDescription: Use appropriate widget types for the number of children
+tags: performance, efficiency, best-practices
+---
+
+## Avoid Single Child in Multi-Child Widget
+
+Multi-child widgets like `Column`, `Row`, `Stack`, `ListView`, or `GridView` are inefficient when used with only a single child. Use single-child optimized widgets like `SizedBox`, `Padding`, `Center`, or `Container` instead.
+
+**Incorrect (inefficient Column):**
+
+```dart
+Column(
+  children: [
+    Text("Only one child here"),
+  ],
+)
+```
+
+**Correct (efficient wrapper):**
+
+```dart
+Padding(
+  padding: const EdgeInsets.all(8.0),
+  child: Text("Only one child here"),
+)
+```
+
+**Tools:** Custom analyzer (D019)

package/skill-assets/sunlint-code-quality/rules/dart/D020-if-else-limit.md

@@ -0,0 +1,41 @@
+---
+title: Limit If/Else Branches
+impact: LOW
+impactDescription: Reduce complexity by limiting the number of if/else branches
+tags: readability, complexity, clean-code
+---
+
+## Limit If/Else Branches
+
+Complex if/else chains with more than 3 branches reduce code readability and increase cyclomatic complexity. When facing multiple branches, consider using `switch` statements, lookup tables (Maps), or the Strategy pattern.
+
+**Incorrect (long if/else chain):**
+
+```dart
+if (type == 'A') {
+  doA();
+} else if (type == 'B') {
+  doB();
+} else if (type == 'C') {
+  doC();
+} else if (type == 'D') {
+  doD();
+} else {
+  doDefault();
+}
+```
+
+**Correct (using switch or Map):**
+
+```dart
+// Option 1: Switch (better readability)
+switch (type) {
+  case 'A': doA(); break;
+  case 'B': doB(); break;
+  case 'C': doC(); break;
+  case 'D': doD(); break;
+  default: doDefault();
+}
+```
+
+**Tools:** Custom analyzer (D020)

package/skill-assets/sunlint-code-quality/rules/dart/D021-negated-booleans.md

@@ -0,0 +1,26 @@
+---
+title: Avoid Negated Boolean Checks
+impact: LOW
+impactDescription: Improve code readability by avoiding inverted or negated boolean conditions
+tags: readability, logic, clean-code
+---
+
+## Avoid Negated Boolean Checks
+
+Negated boolean checks (using `!`) make code harder to read and understand. Replace negative conditions with positive ones wherever possible, and avoid double negations like `!!`.
+
+**Incorrect (fragmented logic):**
+
+```dart
+if (!isNotAuthorized) { ... }
+if (!(a == b)) { ... }
+```
+
+**Correct (clear logic):**
+
+```dart
+if (isAuthorized) { ... }
+if (a != b) { ... }
+```
+
+**Tools:** Custom analyzer (D021)

package/skill-assets/sunlint-code-quality/rules/dart/D022-setstate-usage.md

@@ -0,0 +1,35 @@
+---
+title: Use setState Correctly
+impact: HIGH
+impactDescription: Ensure setState is used correctly in StatefulWidget to avoid performance issues and bugs
+tags: performance, best-practices, lifecycle, state-management
+---
+
+## Use setState Correctly
+
+Common `setState` anti-patterns include: calling `setState` inside `build()`, nesting `setState` calls, making multiple `setState` calls in the same method, or using async callbacks inside `setState`. These lead to performance issues, unnecessary rebuilds, or hard-to-track UI bugs.
+
+**Incorrect (async inside setState):**
+
+```dart
+setState(() async {
+  await fetchData(); // WRONG: setState should be synchronous
+  _data = "new data";
+});
+```
+
+**Correct (sync update after async):**
+
+```dart
+// Fetch data first
+final newData = await fetchData();
+
+// Update state synchronously
+if (mounted) {
+  setState(() {
+    _data = newData;
+  });
+}
+```
+
+**Tools:** Custom analyzer (D022)

package/skill-assets/sunlint-code-quality/rules/dart/D023-unnecessary-overrides.md

@@ -0,0 +1,32 @@
+---
+title: Avoid Unnecessary Method Overrides
+impact: LOW
+impactDescription: Remove methods that only call super with the same parameters as they add no value
+tags: readability, clean-code, refactoring
+---
+
+## Avoid Unnecessary Method Overrides
+
+Methods that override a parent method but only call `super.methodName()` with the same parameters are unnecessary and should be removed. These empty overrides add no functionality and create unnecessary code clutter. Common examples include lifecycle methods like `initState()`, `dispose()`, or `didUpdateWidget()` that only call their super implementation.
+
+**Incorrect (super call only):**
+
+```dart
+@override
+void initState() {
+  super.initState();
+}
+
+@override
+void dispose() {
+  super.dispose();
+}
+```
+
+**Correct (remove if no logic):**
+
+```dart
+// Just remove the method override entirely if it only calls super
+```
+
+**Tools:** Custom analyzer (D023)

package/skill-assets/sunlint-code-quality/rules/dart/D024-avoid-unnecessary-statefulwidget.md

@@ -0,0 +1,45 @@
+---
+title: Avoid Unnecessary StatefulWidget
+impact: LOW
+impactDescription: Use StatelessWidget when no state management is needed to improve performance
+tags: performance, flutter, widgets, best-practices
+---
+
+## Avoid Unnecessary StatefulWidget
+
+StatefulWidget should only be used when the widget needs to maintain mutable state that changes over time. If a widget extends StatefulWidget but its State class has no mutable fields, never calls setState(), and doesn't use lifecycle methods beyond build(), it should be converted to StatelessWidget. StatelessWidget is more efficient as it doesn't maintain state and has less overhead.
+
+**Incorrect (StatefulWidget with no state):**
+
+```dart
+class MyTitle extends StatefulWidget {
+  final String text;
+  const MyTitle({super.key, required this.text});
+
+  @override
+  State<MyTitle> createState() => _MyTitleState();
+}
+
+class _MyTitleState extends State<MyTitle> {
+  @override
+  Widget build(BuildContext context) {
+    return Text(widget.text);
+  }
+}
+```
+
+**Correct (StatelessWidget):**
+
+```dart
+class MyTitle extends StatelessWidget {
+  final String text;
+  const MyTitle({super.key, required this.text});
+
+  @override
+  Widget build(BuildContext context) {
+    return Text(text);
+  }
+}
+```
+
+**Tools:** Custom analyzer (D024)

package/skill-assets/sunlint-code-quality/rules/dart/D025-nested-ternaries.md

@@ -0,0 +1,35 @@
+---
+title: Avoid Nested Conditional Expressions
+impact: LOW
+impactDescription: Improve code readability by avoiding nested ternary operators
+tags: readability, maintainability, clean-code
+---
+
+## Avoid Nested Conditional Expressions
+
+Nested conditional expressions (ternary operators like `a ? b : c ? d : e`) reduce code readability significantly. When logic is complex, use if-else statements or extract the logic into a well-named variable or function.
+
+**Incorrect (hard to follow):**
+
+```dart
+final color = isAdmin ? Colors.red : isLogged ? Colors.green : Colors.grey;
+```
+
+**Correct (descriptive logic):**
+
+```dart
+// Option 1: if-else
+Color userColor;
+if (isAdmin) {
+  userColor = Colors.red;
+} else if (isLogged) {
+  userColor = Colors.green;
+} else {
+  userColor = Colors.grey;
+}
+
+// Option 2: Extracted getter
+Color get userColor => _calculateUserColor();
+```
+
+**Tools:** Custom analyzer (D025)

package/skill-assets/sunlint-code-quality/rules/go/C006-verb-noun-functions.md

@@ -0,0 +1,45 @@
+---
+title: Function Names Verb-Noun
+impact: LOW
+impactDescription: makes code self-documenting
+tags: naming, functions, readability, conventions, quality
+---
+
+## Function Names Verb-Noun
+
+Functions do things. Action verbs make purpose clear.
+
+**Incorrect (vague names):**
+
+```go
+func user() { }           // Noun only
+func userData() { }       // Noun only
+func doSomething() { }    // Vague
+func handleStuff() { }    // Vague
+func manager() { }        // Noun only
+```
+
+**Correct (action verbs):**
+
+```go
+func GetUser() { }
+func CreateUserAccount() { }
+func ValidateEmailFormat() { }
+func CalculateTotalPrice() { }
+func SendConfirmationEmail() { }
+func ConvertCurrencyToUSD() { }
+```
+
+**Verb categories:**
+
+| Category | Verbs |
+|----------|-------|
+| Retrieval | `Get`, `Fetch`, `Find`, `Load`, `Query` |
+| Creation | `Create`, `Build`, `Make`, `Generate` |
+| Modification | `Set`, `Update`, `Modify`, `Change` |
+| Deletion | `Delete`, `Remove`, `Destroy`, `Clear` |
+| Validation | `Validate`, `Verify`, `Check`, `Ensure` |
+| Computation | `Calculate`, `Compute`, `Parse`, `Format` |
+| Boolean | `Is`, `Has`, `Can`, `Should`, `Will` |
+
+**Tools:** PR review, GolangCI-Lint

package/skill-assets/sunlint-code-quality/rules/go/C013-no-dead-code.md

@@ -0,0 +1,48 @@
+---
+title: Do Not Use Dead Code
+impact: LOW
+impactDescription: reduces codebase noise and maintenance burden
+tags: dead-code, cleanup, maintenance, quality
+---
+
+## Do Not Use Dead Code
+
+Dead code confuses readers and increases cognitive load. Git history preserves deleted code.
+
+**Incorrect (keeping dead code):**
+
+```go
+func ProcessOrder(order *Order) float64 {
+	// Old implementation - keeping for reference
+	// total := 0.0
+	// for _, item := range order.Items {
+	// 	total += item.Price * float64(item.Quantity)
+	// }
+	// return total
+
+	total := calculateTotal(order)
+	return total
+}
+
+// Unused function - someone might need it later
+func legacyCalculation() { }
+```
+
+**Correct (clean code):**
+
+```go
+func ProcessOrder(order *Order) float64 {
+	return calculateTotal(order)
+}
+
+// Delete unused functions - git history preserves them
+// Delete commented code - git history preserves it
+```
+
+**Types of dead code:**
+- Commented-out code
+- Unused functions/structs/methods
+- Unreachable code
+- Unused variables (Go compiler will error on these locally, but they may exist in long-lived branches)
+
+**Tools:** gofmt, govet, staticcheck, GolangCI-Lint

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

@@ -0,0 +1,85 @@
+---
+title: Use Dependency Injection
+impact: HIGH
+impactDescription: enables testability and loose coupling
+tags: dependency-injection, testing, coupling, architecture, quality
+---
+
+## Use Dependency Injection
+
+Direct instantiation creates tight coupling, making testing difficult and changes risky. DI enables mockability, replaceability, and testability.
+
+**Incorrect (hardcoded dependencies):**
+
+```go
+type OrderService struct {
+	db     *PostgresDatabase
+	mailer *SendGridMailer
+}
+
+func NewOrderService() *OrderService {
+	return &OrderService{
+		db:     NewPostgresDatabase(), // Hardcoded dependency
+		mailer: NewSendGridMailer(),   // Hardcoded dependency
+	}
+}
+
+func (s *OrderService) CreateOrder(data OrderData) error {
+	order, err := s.db.Insert("orders", data)
+	if err != nil {
+		return err
+	}
+	return s.mailer.Send(data.Email, "Order created")
+}
+```
+
+**Correct (injected dependencies via interfaces):**
+
+```go
+type Database interface {
+	Insert(table string, data any) (any, error)
+}
+
+type Mailer interface {
+	Send(to string, message string) error
+}
+
+type OrderService struct {
+	db     Database
+	mailer Mailer
+}
+
+func NewOrderService(db Database, mailer Mailer) *OrderService {
+	return &OrderService{
+		db:     db,
+		mailer: mailer,
+	}
+}
+
+func (s *OrderService) CreateOrder(data OrderData) error {
+	order, err := s.db.Insert("orders", data)
+	if err != nil {
+		return err
+	}
+	return s.mailer.Send(data.Email, "Order created")
+}
+
+// Usage
+service := NewOrderService(
+	NewPostgresDatabase(connString),
+	NewSendGridMailer(apiKey),
+)
+
+// Testing
+mockDb := new(MockDatabase)
+mockMailer := new(MockMailer)
+testService := NewOrderService(mockDb, mockMailer)
+```
+
+**Benefits:**
+- Easy mocking for unit tests
+- Swappable implementations
+- Clear dependencies visible in constructor/factory
+- Supports interface-based design (accept interfaces, return structs)
+
+**Tools:** GolangCI-Lint, Manual review

package/skill-assets/sunlint-code-quality/rules/go/C017-no-constructor-logic.md

@@ -0,0 +1,67 @@
+---
+title: No Business Logic In Factory Functions
+impact: HIGH
+impactDescription: ensures predictable object initialization
+tags: factory, initialization, side-effects, patterns, quality
+---
+
+## No Business Logic In Factory Functions
+
+Factory functions (e.g., `NewService`) should only initialize state. Side effects in factory functions are unexpected and make testing difficult.
+
+**Incorrect (logic in factory function):**
+
+```go
+type UserService struct {
+	config Config
+}
+
+func NewUserService(configPath string) (*UserService, error) {
+	// BAD: Reading files in factory function
+	rawConfig, err := os.ReadFile(configPath)
+	if err != nil {
+		return nil, err
+	}
+	var config Config
+	json.Unmarshal(rawConfig, &config)
+	
+	// BAD: Network calls/API initialization here
+	resp, _ := http.Get("https://api.example.com/init")
+	
+	// BAD: Logging/side effects
+	log.Println("UserService initialized")
+	
+	return &UserService{config: config}, nil
+}
+```
+
+**Correct (clear separation):**
+
+```go
+type UserService struct {
+	config     Config
+	httpClient *http.Client
+}
+
+func NewUserService(config Config, httpClient *http.Client) *UserService {
+	// Only assignment - no side effects
+	return &UserService{
+		config:     config,
+		httpClient: httpClient,
+	}
+}
+
+// Service initialization in main or a dedicated bootstrapper
+func InitializeApp() {
+	rawConfig, _ := os.ReadFile("./config.json")
+	var config Config
+	json.Unmarshal(rawConfig, &config)
+	
+	httpClient := &http.Client{Timeout: 10 * time.Second}
+	
+	service := NewUserService(config, httpClient)
+	log.Println("UserService ready")
+}
+```
+
+**Tools:** PR review, Manual review

package/skill-assets/sunlint-code-quality/rules/go/C018-generic-errors.md

@@ -0,0 +1,63 @@
+---
+title: Do Not Return Generic Errors
+impact: HIGH
+impactDescription: enables proper error handling and monitoring
+tags: error-handling, custom-errors, debugging, quality
+---
+
+## Do Not Return Generic Errors
+
+Generic errors (like `errors.New("error")`) lack context needed for debugging. They make it impossible to distinguish between error types for proper handling.
+
+**Incorrect (generic errors):**
+
+```go
+if user == nil {
+	return errors.New("error")
+}
+
+if !isValid {
+	return fmt.Errorf("invalid")
+}
+```
+
+**Correct (specific custom errors or sentinel errors):**
+
+```go
+// Sentinel errors for simple checks
+var ErrUserNotFound = errors.New("user not found")
+
+func (s *Service) GetUser(id string) (*User, error) {
+	if user == nil {
+		return nil, fmt.Errorf("%w: user with ID %s not found", ErrUserNotFound, id)
+	}
+	return user, nil
+}
+
+// Custom error types for complex context
+type ValidationError struct {
+	Field   string
+	Message string
+	Value   any
+}
+
+func (e *ValidationError) Error() string {
+	return fmt.Sprintf("validation failed on %s: %s", e.Field, e.Message)
+}
+
+if !isValid {
+	return &ValidationError{
+		Field:   "email",
+		Message: "invalid format",
+		Value:   email,
+	}
+}
+```
+
+Custom errors should include:
+- Descriptive message with context (use `%w` for wrapping)
+- Error codes or types for programmatic handling (using `errors.Is` or `errors.As`)
+- Relevant data for debugging
+- Appropriate mapping to status codes in the transport layer (e.g., HTTP 404)
+
+**Tools:** GolangCI-Lint (errname, goerr113), Manual review

package/skill-assets/sunlint-code-quality/rules/go/C019-error-log-level.md

@@ -0,0 +1,50 @@
+---
+title: Do Not Use Error Log For Non-critical
+impact: HIGH
+impactDescription: prevents alert fatigue and log noise
+tags: logging, log-levels, error, observability, quality
+---
+
+## Do Not Use Error Log For Non-critical
+
+Incorrect log levels cause alert fatigue and hide real issues. When everything is an "error", nothing is.
+
+**Incorrect (overusing error level):**
+
+```go
+// NOT an error - expected business case
+slog.Error("User entered wrong password")
+
+// NOT an error - validation failure
+slog.Error("Email format invalid")
+
+// NOT an error - temporary network issue
+slog.Error("Retry attempt 2 of 5")
+```
+
+**Correct (appropriate log levels using slog):**
+
+```go
+// WARN - recoverable, may need attention
+slog.Warn("Payment retry attempt", "attempt", 2, "max_attempts", 5)
+
+// INFO - normal business events
+slog.Info("Login failed - invalid password", "user_id", userID, "attempts", 3)
+
+// DEBUG - detailed troubleshooting
+slog.Debug("Validation failed", "field", "email", "value", maskedEmail)
+
+// ERROR - only for actual system failures
+slog.Error("Database connection lost", "host", dbHost, "error", err)
+```
+
+**Log Level Guide:**
+
+| Level | Use For |
+|-------|---------|
+| ERROR | System failures, crashes, unrecoverable |
+| WARN  | Potential issues, degraded performance |
+| INFO  | Business events, state changes |
+| DEBUG | Detailed troubleshooting |
+
+**Tools:** Log linter, Custom rule, `slog` (standard library)