@sun-asterisk/sunlint 1.3.41 → 1.3.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sunlint",
-  "version": "1.3.41",
+  "version": "1.3.42",
   "description": "☀️ SunLint - Multi-language static analysis tool for code quality and security | Sun* Engineering Standards",
   "main": "cli.js",
   "bin": {

package/skill-assets/sunlint-code-quality/rules/dart/D001-recommended-lints.md

@@ -0,0 +1,36 @@
+---
+title: Recommended Lint Rules Should Be Enabled
+impact: MEDIUM
+impactDescription: Ensure code quality through standard lint configurations
+tags: lint, quality, static-analysis
+---
+
+## Recommended Lint Rules Should Be Enabled
+
+The `analysis_options.yaml` file should include recommended lint packages (flutter_lints, very_good_analysis, or lints) and critical lint rules should not be disabled. This ensures consistent code quality standards across the project.
+
+**Incorrect (minimal components):**
+
+```yaml
+analyzer:
+  exclude:
+    - build/**
+```
+
+**Correct (recommended setup):**
+
+```yaml
+include: package:flutter_lints/flutter.yaml
+
+analyzer:
+  exclude:
+    - "**/*.g.dart"
+    - "**/*.freezed.dart"
+
+linter:
+  rules:
+    - avoid_print
+    - prefer_const_constructors
+```
+
+**Tools:** Custom analyzer (D001)

package/skill-assets/sunlint-code-quality/rules/dart/D002-dispose-resources.md

@@ -0,0 +1,44 @@
+---
+title: Always Dispose Resources and Remove Listeners
+impact: HIGH
+impactDescription: Prevent memory leaks by ensuring proper resource disposal
+tags: memory-leak, resources, disposal, lifecycle, performance
+---
+
+## Always Dispose Resources and Remove Listeners
+
+All disposable resources (Controllers, StreamSubscriptions, FocusNodes, Listeners) must be properly disposed in the `dispose()` method. This includes TextEditingController, AnimationController, ScrollController, StreamSubscription, FocusNode, and other resources that implement Disposable. Failing to dispose these resources leads to memory leaks.
+
+**Incorrect (not disposed):**
+
+```dart
+class _MyWidgetState extends State<MyWidget> {
+  final _controller = TextEditingController();
+
+  @override
+  Widget build(BuildContext context) {
+    return TextField(controller: _controller);
+  }
+}
+```
+
+**Correct (properly disposed):**
+
+```dart
+class _MyWidgetState extends State<MyWidget> {
+  final _controller = TextEditingController();
+
+  @override
+  void dispose() {
+    _controller.dispose();
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return TextField(controller: _controller);
+  }
+}
+```
+
+**Tools:** Custom analyzer (D002)

package/skill-assets/sunlint-code-quality/rules/dart/D003-prefer-widget-classes.md

@@ -0,0 +1,53 @@
+---
+title: Prefer Widgets Over Methods Returning Widgets
+impact: LOW
+impactDescription: Improve performance and maintainability by extracting widget-returning methods into widget classes
+tags: performance, maintainability, widgets, extraction
+---
+
+## Prefer Widgets Over Methods Returning Widgets
+
+Methods that return widgets should be extracted into separate StatelessWidget or StatefulWidget classes. This improves performance as Flutter can optimize widget rebuilds, makes code more reusable, and follows Flutter best practices. Only the build() method and lifecycle methods are exempt from this rule.
+
+**Incorrect (method returning widget):**
+
+```dart
+Widget _buildHeader() {
+  return Text("Title", style: TextStyle(fontSize: 24));
+}
+
+@override
+Widget build(BuildContext context) {
+  return Column(
+    children: [
+      _buildHeader(),
+      Text("Content"),
+    ],
+  );
+}
+```
+
+**Correct (extracted widget class):**
+
+```dart
+class HeaderWidget extends StatelessWidget {
+  const HeaderWidget({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return Text("Title", style: TextStyle(fontSize: 24));
+  }
+}
+
+@override
+Widget build(BuildContext context) {
+  return Column(
+    children: [
+      const HeaderWidget(),
+      Text("Content"),
+    ],
+  );
+}
+```
+
+**Tools:** Custom analyzer (D003)

package/skill-assets/sunlint-code-quality/rules/dart/D004-avoid-shrinkwrap.md

@@ -0,0 +1,31 @@
+---
+title: Avoid shrinkWrap in ListView
+impact: LOW
+impactDescription: Prevent performance issues caused by shrinkWrap in scrollable widgets
+tags: performance, scroll, listview, lazy-loading
+---
+
+## Avoid shrinkWrap in ListView
+
+Using `shrinkWrap: true` in ListView or GridView disables lazy loading and forces all items to render at once, causing severe performance degradation. Instead, use Expanded or Flexible widgets to constrain the ListView size, or use SliverList within a CustomScrollView for better performance. The shrinkWrap parameter should only be used in rare cases where the list is guaranteed to be small.
+
+**Incorrect (using shrinkWrap):**
+
+```dart
+ListView(
+  shrinkWrap: true,
+  children: [ ... ],
+)
+```
+
+**Correct (using Expanded):**
+
+```dart
+Expanded(
+  child: ListView(
+    children: [ ... ],
+  ),
+)
+```
+
+**Tools:** Custom analyzer (D004)

package/skill-assets/sunlint-code-quality/rules/dart/D005-widget-nesting.md

@@ -0,0 +1,62 @@
+---
+title: Limit Widget Nesting Depth to 6
+impact: LOW
+impactDescription: Maintain code readability and prevent performance issues caused by deeply nested widgets
+tags: readability, maintainability, performance, nesting
+---
+
+## Limit Widget Nesting Depth to 6
+
+Widget nesting should not exceed 6 levels in the build method. Deeply nested widgets make code harder to understand, maintain, and can impact performance. When nesting exceeds this limit, extract nested widgets into separate StatelessWidget or StatefulWidget classes.
+
+**Incorrect (deeply nested):**
+
+```dart
+@override
+Widget build(BuildContext context) {
+  return Scaffold(
+    body: Center(
+      child: Container(
+        padding: const EdgeInsets.all(16),
+        child: Column(
+          children: [
+            Padding(
+              padding: const EdgeInsets.only(bottom: 8),
+              child: Row(
+                children: [
+                  Expanded(
+                    child: Card(
+                      child: Padding(
+                        padding: const EdgeInsets.all(12),
+                        child: Text("Too deep!"), // Level 11
+                      ),
+                    ),
+                  ),
+                ],
+              ),
+            ),
+          ],
+        ),
+      ),
+    ),
+  );
+}
+```
+
+**Correct (extracted widget):**
+
+```dart
+@override
+Widget build(BuildContext context) {
+  return Scaffold(
+    body: Center(
+      child: Container(
+        padding: const EdgeInsets.all(16),
+        child: const MyCustomHeader(), // Extracted at level 4
+      ),
+    ),
+  );
+}
+```
+
+**Tools:** Custom analyzer (D005)

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)