@sun-asterisk/sunlint 1.3.41 → 1.3.43

package/skill-assets/sunlint-code-quality/rules/dart/D006-large-callbacks.md

@@ -0,0 +1,54 @@
+---
+title: Prefer Extracting Large Callbacks from Build
+impact: LOW
+impactDescription: Improve code readability and testability by extracting large callback functions
+tags: readability, maintainability, testability, callback
+---
+
+## Prefer Extracting Large Callbacks from Build
+
+Callback functions (onTap, onPressed, onChanged, etc.) in widget builders should not exceed 5 lines. Large inline callbacks make the build method harder to read and maintain. Extract callbacks that exceed this limit to separate methods or functions.
+
+**Incorrect (large inline callback):**
+
+```dart
+@override
+Widget build(BuildContext context) {
+  return ElevatedButton(
+    onPressed: () {
+      final data = _formKey.currentState?.value;
+      if (data != null && data.isNotEmpty) {
+        _logger.info('Submitting data: $data');
+        _repository.save(data).then((_) {
+          Navigator.pop(context);
+        });
+      }
+    },
+    child: Text('Submit'),
+  );
+}
+```
+
+**Correct (extracted callback method):**
+
+```dart
+void _handleSubmit() {
+  final data = _formKey.currentState?.value;
+  if (data != null && data.isNotEmpty) {
+    _logger.info('Submitting data: $data');
+    _repository.save(data).then((_) {
+      Navigator.pop(context);
+    });
+  }
+}
+
+@override
+Widget build(BuildContext context) {
+  return ElevatedButton(
+    onPressed: _handleSubmit,
+    child: Text('Submit'),
+  );
+}
+```
+
+**Tools:** Custom analyzer (D006)

package/skill-assets/sunlint-code-quality/rules/dart/D007-lifecycle-order.md

@@ -0,0 +1,44 @@
+---
+title: Prefer Init First, Dispose Last
+impact: MEDIUM
+impactDescription: Ensure proper lifecycle method ordering in StatefulWidget
+tags: lifecycle, maintenance, flutter, statefulwidget
+---
+
+## Prefer Init First, Dispose Last
+
+In StatefulWidget lifecycle methods, `super.initState()` should be called first before any initialization code, and `super.dispose()` should be called last after all cleanup code. This ensures that the framework's internal state management is properly initialized before your code runs and is the last to clean up.
+
+**Incorrect (wrong order):**
+
+```dart
+@override
+void initState() {
+  _controller = TextEditingController();
+  super.initState(); // Called after custom logic
+}
+
+@override
+void dispose() {
+  super.dispose(); // Called before cleanup
+  _controller.dispose();
+}
+```
+
+**Correct (framework-friendly order):**
+
+```dart
+@override
+void initState() {
+  super.initState(); // Always first
+  _controller = TextEditingController();
+}
+
+@override
+void dispose() {
+  _controller.dispose();
+  super.dispose(); // Always last
+}
+```
+
+**Tools:** Custom analyzer (D007)

package/skill-assets/sunlint-code-quality/rules/dart/D008-long-functions.md

@@ -0,0 +1,37 @@
+---
+title: Avoid Long Functions
+impact: MEDIUM
+impactDescription: Improve code readability and maintainability by limiting function length
+tags: readability, maintainability, clean-code, dev-efficiency
+---
+
+## Avoid Long Functions
+
+Functions should not exceed 60 lines of effective code (excluding comments and opening/closing braces). Long functions are harder to understand, test, and maintain. They often indicate that the function is doing too much and should be broken down into smaller, more focused functions.
+
+**Incorrect (too long):**
+
+```dart
+void processOrder(Order order) {
+  // Line 1
+  // ... 60+ more lines of logic ...
+  // Line 70
+}
+```
+
+**Correct (modular functions):**
+
+```dart
+void processOrder(Order order) {
+  validateOrder(order);
+  calculateTotal(order);
+  saveToDatabase(order);
+  sendNotification(order);
+}
+
+void validateOrder(Order order) { ... }
+void calculateTotal(Order order) { ... }
+// Each function is focused and short
+```
+
+**Tools:** Custom analyzer (D008)

package/skill-assets/sunlint-code-quality/rules/dart/D009-function-parameters.md

@@ -0,0 +1,38 @@
+---
+title: Limit Function Parameters
+impact: MEDIUM
+impactDescription: Improve code readability by limiting the number of function parameters
+tags: readability, maintainability, clean-code
+---
+
+## Limit Function Parameters
+
+Functions, methods, and constructors should not have more than 5 parameters. Too many parameters make code harder to read, understand, and maintain. When a function needs many parameters, consider grouping related parameters into a data class or using a configuration object.
+
+**Incorrect (too many positional parameters):**
+
+```dart
+void createUser(String firstName, String lastName, int age, String email, String phone, String address, String city) {
+  // ...
+}
+```
+
+**Correct (using data object or named parameters):**
+
+```dart
+// Option 1: Data class
+void createUser(UserDetail details) {
+  // ...
+}
+
+// Option 2: Grouped named parameters
+void createUser({
+  required String name,
+  required ContactInfo contact,
+  required Address address,
+}) {
+  // ...
+}
+```
+
+**Tools:** Custom analyzer (D009)

package/skill-assets/sunlint-code-quality/rules/dart/D010-cyclomatic-complexity.md

@@ -0,0 +1,46 @@
+---
+title: Limit Cyclomatic Complexity
+impact: MEDIUM
+impactDescription: Improve code readability and maintainability by limiting cyclomatic complexity
+tags: complexity, maintainability, clean-code
+---
+
+## Limit Cyclomatic Complexity
+
+Functions, methods, and constructors should not have cyclomatic complexity exceeding 10. High cyclomatic complexity indicates that the code has too many independent paths, making it harder to understand, test, and maintain. Use early returns or extract complex logic into sub-functions.
+
+**Incorrect (high complexity):**
+
+```dart
+String getStatusDescription(int status, bool isUrgent, bool isAdmin) {
+  if (status == 1) {
+    if (isUrgent) return "Urgent Pending";
+    return "Pending";
+  } else if (status == 2) {
+    if (isAdmin) return "Admin Approved";
+    return "Approved";
+  } else if (status == 3) {
+    return "Rejected";
+  } else {
+    return "Unknown";
+  }
+}
+```
+
+**Correct (reduced complexity with Map or early returns):**
+
+```dart
+static const statusMap = {
+  1: "Pending",
+  2: "Approved",
+  3: "Rejected",
+};
+
+String getStatusDescription(int status, bool isUrgent, bool isAdmin) {
+  if (status == 1 && isUrgent) return "Urgent Pending";
+  if (status == 2 && isAdmin) return "Admin Approved";
+  return statusMap[status] ?? "Unknown";
+}
+```
+
+**Tools:** Custom analyzer (D010)

package/skill-assets/sunlint-code-quality/rules/dart/D011-named-parameters.md

@@ -0,0 +1,31 @@
+---
+title: Prefer Named Parameters
+impact: LOW
+impactDescription: Improve code readability and prevent parameter confusion
+tags: readability, safety, clean-code
+---
+
+## Prefer Named Parameters
+
+Functions, methods, and constructors with more than 3 parameters that have 2 or more adjacent parameters of the same type should use named parameters. This improves code clarity by making it explicit which value corresponds to which parameter, reducing the risk of accidentally swapping arguments of the same type.
+
+**Incorrect (confusing positional parameters):**
+
+```dart
+// At call site, hard to tell which is width and which is height
+final rect = Rectangle(100.0, 50.0, 10.0, "red");
+```
+
+**Correct (clear named parameters):**
+
+```dart
+// Much clearer at call site
+final rect = Rectangle(
+  width: 100.0,
+  height: 50.0,
+  padding: 10.0,
+  color: "red",
+);
+```
+
+**Tools:** Custom analyzer (D011)

package/skill-assets/sunlint-code-quality/rules/dart/D012-named-booleans.md

@@ -0,0 +1,28 @@
+---
+title: Prefer Named Boolean Parameters
+impact: LOW
+impactDescription: Improve code readability by avoiding unclear boolean parameters
+tags: readability, clean-code, boolean
+---
+
+## Prefer Named Boolean Parameters
+
+Boolean parameters in functions make code harder to understand at call sites (the "Boolean Trap"). When a function has boolean parameters, use named parameters to make the intent explicit. Better yet, create separate functions (e.g., `enableUser()` instead of `setUser(true)`).
+
+**Incorrect (unclear boolean meaning):**
+
+```dart
+updateStatus(user, true); // What does true mean? Is it active? deleted? admin?
+```
+
+**Correct (explicit naming):**
+
+```dart
+// Option 1: Named parameter
+updateStatus(user, isActive: true);
+
+// Option 2: Semantic function
+activateUser(user);
+```
+
+**Tools:** Custom analyzer (D012)

package/skill-assets/sunlint-code-quality/rules/dart/D013-single-public-class.md

@@ -0,0 +1,34 @@
+---
+title: Prefer a Single Public Class Per File
+impact: LOW
+impactDescription: Improve code organization and maintainability
+tags: organization, maintainability, clean-code
+---
+
+## Prefer a Single Public Class Per File
+
+Each Dart file should contain only one public class. Multiple public classes in a single file make code harder to navigate, test, and maintain. Private implementation classes (starting with `_`) are allowed in the same file.
+
+**Incorrect (multiple public classes):**
+
+```dart
+// user_models.dart
+class User { ... }
+class UserProfile { ... }
+class UserSettings { ... }
+```
+
+**Correct (split into separate files):**
+
+```dart
+// user.dart
+class User { ... }
+
+// user_profile.dart
+class UserProfile { ... }
+
+// user_settings.dart
+class UserSettings { ... }
+```
+
+**Tools:** Custom analyzer (D013)

package/skill-assets/sunlint-code-quality/rules/dart/D014-safe-collection-access.md

@@ -0,0 +1,30 @@
+---
+title: Avoid Unsafe Collection Access
+impact: HIGH
+impactDescription: Prevent runtime errors from accessing empty collections
+tags: safety, stability, collections, crash-prevention
+---
+
+## Avoid Unsafe Collection Access
+
+Using `.first`, `.last`, or `.single` on collections without checking if they're empty causes runtime `StateError` exceptions. Always check `isEmpty`, `isNotEmpty`, or use safe alternatives from `collection` package or built-in `firstOrNull`.
+
+**Incorrect (potential crash):**
+
+```dart
+final firstUser = users.first; // Throws StateError if users is empty
+```
+
+**Correct (safe access):**
+
+```dart
+// Option 1: check length
+if (users.isNotEmpty) {
+  final firstUser = users.first;
+}
+
+// Option 2: use null-safe getter (Dart 3.0+)
+final firstUser = users.firstOrNull;
+```
+
+**Tools:** Custom analyzer (D014)

package/skill-assets/sunlint-code-quality/rules/dart/D015-copywith-consistency.md

@@ -0,0 +1,52 @@
+---
+title: Ensure copyWith includes all constructor parameters
+impact: MEDIUM
+impactDescription: Maintain data integrity and completeness in immutable objects
+tags: safety, immutability, data-integrity, boilerplate
+---
+
+## Ensure copyWith includes all constructor parameters
+
+When a class implements a `copyWith` method for creating modified copies, it should include all constructor parameters. Missing parameters in `copyWith` can lead to unintended data loss or inability to update certain fields. This is especially important for data classes, models, and immutable state objects.
+
+**Incorrect (incomplete copyWith):**
+
+```dart
+class User {
+  final String id;
+  final String name;
+  final int age;
+
+  User({required this.id, required this.name, required this.age});
+
+  User copyWith({String? name}) {
+    return User(
+      id: this.id,
+      name: name ?? this.name,
+      age: this.age, // age cannot be updated via copyWith
+    );
+  }
+}
+```
+
+**Correct (complete copyWith):**
+
+```dart
+class User {
+  final String id;
+  final String name;
+  final int age;
+
+  User({required this.id, required this.name, required this.age});
+
+  User copyWith({String? name, int? age}) {
+    return User(
+      id: this.id,
+      name: name ?? this.name,
+      age: age ?? this.age,
+    );
+  }
+}
+```
+
+**Tools:** Custom analyzer (D015)

package/skill-assets/sunlint-code-quality/rules/dart/D016-project-tests.md

@@ -0,0 +1,32 @@
+---
+title: Project should have tests
+impact: HIGH
+impactDescription: Ensure code quality and prevent regressions through automated testing
+tags: testing, quality, reliability
+---
+
+## Project should have tests
+
+Every Dart/Flutter project should have a `test` directory containing test files (files ending with `_test.dart`). Tests are essential for maintaining code quality, catching bugs early, and enabling safe refactoring.
+
+**Incorrect (no tests):**
+
+```text
+my_project/
+  lib/
+  pubspec.yaml
+  # MISSING test/ directory
+```
+
+**Correct (testing infrastructure included):**
+
+```text
+my_project/
+  lib/
+  test/
+    unit_test.dart
+    widget_test.dart
+  pubspec.yaml
+```
+
+**Tools:** Custom analyzer (D016)

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)