@sun-asterisk/sunlint 1.3.48 → 1.3.49

package/skill-assets/sunlint-code-quality/rules/dart/C022-no-unused-variables.md

@@ -0,0 +1,50 @@
+---
+title: Do Not Leave Unused Variables
+impact: LOW
+impactDescription: reduces code noise and potential bugs
+tags: variables, cleanup, quality
+---
+
+## Do Not Leave Unused Variables
+
+Unused variables suggest incomplete refactoring or bugs.
+
+**Incorrect (unused variables):**
+
+```dart
+void processOrder(Order order) {
+  final user = order.user;   // Never used
+  final total = order.total; // Never used
+  final items = order.items;
+
+  return items.map((i) => i.name).toList();
+}
+```
+
+**Correct (only needed variables):**
+
+```dart
+void processOrder(Order order) {
+  return order.items.map((i) => i.name).toList();
+}
+
+// If destructuring/pattern matching, prefix with _ for intentionally ignored
+void handleEvent(Map<String, dynamic> event) {
+  final type = event['type'] as String;
+  final _ = event['payload']; // Intentionally ignored
+  print('Event: $type');
+}
+```
+
+**Enable via analysis_options.yaml:**
+
+```yaml
+# analysis_options.yaml
+linter:
+  rules:
+    - unused_local_variable
+    - unused_element
+    - avoid_unused_constructor_parameters
+```
+
+**Tools:** dart analyze, `unused_local_variable` lint rule

package/skill-assets/sunlint-code-quality/rules/dart/C023-no-duplicate-names.md

@@ -0,0 +1,56 @@
+---
+title: No Duplicate Variable Names In Scope
+impact: HIGH
+impactDescription: prevents shadowing bugs
+tags: variables, shadowing, scope, quality
+---
+
+## No Duplicate Variable Names In Scope
+
+Variable shadowing causes subtle bugs where inner variables hide outer ones.
+
+**Incorrect (shadowed variables):**
+
+```dart
+final user = getCurrentUser();
+
+void processOrder(Order order) {
+  final user = order.user; // Shadows outer user!
+
+  // Which user is this?
+  print(user.name);
+}
+
+// Same name in nested scope
+for (final item in items) {
+  final item = transform(item); // Shadows loop variable!
+}
+```
+
+**Correct (unique names):**
+
+```dart
+final currentUser = getCurrentUser();
+
+void processOrder(Order order) {
+  final orderUser = order.user; // Clear distinction
+
+  print(orderUser.name);
+}
+
+// Different names in nested scope
+for (final item in items) {
+  final transformedItem = transform(item);
+}
+```
+
+**Enable via analysis_options.yaml:**
+
+```yaml
+# analysis_options.yaml
+linter:
+  rules:
+    - no_leading_underscores_for_local_identifiers
+```
+
+**Tools:** dart analyze, Code Review

package/skill-assets/sunlint-code-quality/rules/dart/C024-centralize-constants.md

@@ -0,0 +1,75 @@
+---
+title: Centralize Constants
+impact: HIGH
+impactDescription: makes values easy to find and update
+tags: constants, magic-numbers, configuration, quality
+---
+
+## Centralize Constants
+
+Magic numbers scattered throughout code are hard to find and change.
+
+**Incorrect (magic numbers):**
+
+```dart
+if (password.length < 8) { }
+if (retryCount > 3) { }
+if (status == 1) { }
+await Future.delayed(const Duration(milliseconds: 300000));
+if (user.role == 'admin') { }
+```
+
+**Correct (centralized constants):**
+
+```dart
+// lib/constants/app_constants.dart
+class AppConstants {
+  AppConstants._(); // Prevent instantiation
+
+  static const int passwordMinLength = 8;
+  static const int maxRetryAttempts = 3;
+  static const Duration sessionTimeout = Duration(minutes: 5);
+}
+
+class OrderStatus {
+  OrderStatus._();
+
+  static const int pending = 1;
+  static const int approved = 2;
+  static const int shipped = 3;
+}
+
+class UserRole {
+  UserRole._();
+
+  static const String admin = 'admin';
+  static const String user = 'user';
+  static const String guest = 'guest';
+}
+
+// Usage
+if (password.length < AppConstants.passwordMinLength) { }
+if (retryCount > AppConstants.maxRetryAttempts) { }
+if (status == OrderStatus.pending) { }
+await Future.delayed(AppConstants.sessionTimeout);
+if (user.role == UserRole.admin) { }
+```
+
+**Alternative: use enums for type-safe values:**
+
+```dart
+enum OrderStatus { pending, approved, shipped }
+enum UserRole { admin, user, guest }
+
+// Usage
+if (order.status == OrderStatus.pending) { }
+if (user.role == UserRole.admin) { }
+```
+
+**Benefits:**
+- Single source of truth
+- Self-documenting
+- Easy to update
+- Type safety with enums
+
+**Tools:** dart analyze, Code Review

package/skill-assets/sunlint-code-quality/rules/dart/C029-catch-log-root-cause.md

@@ -0,0 +1,53 @@
+---
+title: All Catch Blocks Must Log Root Cause
+impact: HIGH
+impactDescription: enables debugging and incident response
+tags: error-handling, logging, debugging, observability, quality
+---
+
+## All Catch Blocks Must Log Root Cause
+
+Silent failures make debugging impossible. Without proper logging, you cannot trace issues in production.
+
+**Incorrect (silent or minimal logging):**
+
+```dart
+try {
+  await processPayment(order);
+} catch (e) {
+  // Empty catch - silent failure!
+}
+
+try {
+  await saveUser(user);
+} catch (e) {
+  return null; // No logging, no context
+}
+```
+
+**Correct (comprehensive error logging):**
+
+```dart
+try {
+  await processPayment(order);
+} catch (e, st) {
+  logger.e(
+    'Payment processing failed',
+    error: e,
+    stackTrace: st,
+  );
+  logger.e('Context: orderId=${order.id}, userId=${order.userId}, amount=${order.amount}');
+  throw PaymentFailedException(
+    'Payment could not be processed',
+    cause: e,
+  );
+}
+```
+
+**Log context should include:**
+- Error object and stack trace (`error:`, `stackTrace:`)
+- Relevant entity IDs (order, user, etc.)
+- Input that caused the error
+- Timing information
+
+**Tools:** logger package, Code Review

package/skill-assets/sunlint-code-quality/rules/dart/C030-custom-error-classes.md

@@ -0,0 +1,86 @@
+---
+title: Use Custom Exception Classes
+impact: HIGH
+impactDescription: enables proper error categorization and handling
+tags: error-handling, custom-errors, exceptions, patterns, quality
+---
+
+## Use Custom Exception Classes
+
+Custom exception classes enable proper error handling, categorization, and monitoring. They provide clear contracts for callers.
+
+**Incorrect (generic exceptions):**
+
+```dart
+throw Exception('User not found');
+throw Exception('Invalid input');
+throw Exception('Network error');
+```
+
+**Correct (custom exception hierarchy):**
+
+```dart
+// Base application exception
+class AppException implements Exception {
+  const AppException(this.message, {this.code, this.context});
+
+  final String message;
+  final String? code;
+  final Map<String, dynamic>? context;
+
+  @override
+  String toString() => 'AppException($code): $message';
+}
+
+// Specific exceptions
+class UserNotFoundException extends AppException {
+  UserNotFoundException(String userId)
+      : super(
+          'User $userId not found',
+          code: 'USER_NOT_FOUND',
+          context: {'userId': userId},
+        );
+}
+
+class ValidationException extends AppException {
+  ValidationException({required String field, required String message})
+      : super(
+          message,
+          code: 'VALIDATION_ERROR',
+          context: {'field': field},
+        );
+}
+
+class NetworkException extends AppException {
+  NetworkException({required int statusCode, required String endpoint})
+      : super(
+          'Network request failed with status $statusCode',
+          code: 'NETWORK_ERROR',
+          context: {'statusCode': statusCode, 'endpoint': endpoint},
+        );
+}
+
+// Usage
+throw UserNotFoundException(userId);
+throw ValidationException(field: 'email', message: 'Invalid email format');
+throw NetworkException(statusCode: response.statusCode, endpoint: '/users');
+
+// Handling
+try {
+  await fetchUser(id);
+} on UserNotFoundException catch (e) {
+  showNotFoundScreen();
+} on NetworkException catch (e) {
+  showNetworkError();
+} on AppException catch (e) {
+  showGenericError(e.message);
+}
+```
+
+**Benefits:**
+- Type-safe error handling with `on`
+- Structured error context
+- Consistent error format
+- Clear error hierarchy
+
+**Tools:** Code Review, dart_analyzer

package/skill-assets/sunlint-code-quality/rules/dart/C033-separate-data-access.md

@@ -0,0 +1,90 @@
+---
+title: Separate Processing And Data Access
+impact: HIGH
+impactDescription: enables testable business logic
+tags: separation, repository, service, architecture, quality
+---
+
+## Separate Processing And Data Access
+
+Mixing business logic with database/API access creates tight coupling and makes testing require real databases or network.
+
+**Incorrect (mixed concerns):**
+
+```dart
+class OrderService {
+  final database = DatabaseHelper.instance;
+
+  Future<double> calculateDiscount(String userId) async {
+    // Business logic mixed with data access
+    final userMap = await database.query(
+      'users',
+      where: 'id = ?',
+      whereArgs: [userId],
+    );
+    final orderMaps = await database.query(
+      'orders',
+      where: 'user_id = ?',
+      whereArgs: [userId],
+    );
+
+    double discount = 0;
+    if (orderMaps.length > 10) discount += 5;
+    if (userMap.first['is_premium'] == 1) discount += 10;
+
+    return discount;
+  }
+}
+```
+
+**Correct (separated layers):**
+
+```dart
+// Repository - data access only
+abstract class IUserRepository {
+  Future<User?> findById(String userId);
+}
+
+abstract class IOrderRepository {
+  Future<List<Order>> findByUserId(String userId);
+}
+
+class SqlUserRepository implements IUserRepository {
+  SqlUserRepository(this._db);
+  final DatabaseHelper _db;
+
+  @override
+  Future<User?> findById(String userId) async {
+    final maps = await _db.query('users', where: 'id = ?', whereArgs: [userId]);
+    return maps.isEmpty ? null : User.fromMap(maps.first);
+  }
+}
+
+// Service - business logic only
+class DiscountService {
+  DiscountService({
+    required IUserRepository userRepo,
+    required IOrderRepository orderRepo,
+  }) : _userRepo = userRepo,
+       _orderRepo = orderRepo;
+
+  final IUserRepository _userRepo;
+  final IOrderRepository _orderRepo;
+
+  Future<double> calculateDiscount(String userId) async {
+    final user = await _userRepo.findById(userId);
+    final orders = await _orderRepo.findByUserId(userId);
+
+    return _computeDiscount(user, orders);
+  }
+
+  double _computeDiscount(User? user, List<Order> orders) {
+    double discount = 0;
+    if (orders.length > 10) discount += 5;
+    if (user?.isPremium == true) discount += 10;
+    return discount;
+  }
+}
+```
+
+**Tools:** Code Review, Architecture Review

package/skill-assets/sunlint-code-quality/rules/dart/C035-error-context-logging.md

@@ -0,0 +1,62 @@
+---
+title: Log All Relevant Context On Errors
+impact: HIGH
+impactDescription: enables quick debugging and incident response
+tags: error-handling, logging, context, debugging, quality
+---
+
+## Log All Relevant Context On Errors
+
+Context-rich logs enable quick debugging. Without proper context, finding root causes is like finding a needle in a haystack.
+
+**Incorrect (minimal context):**
+
+```dart
+logger.e('Error occurred');
+logger.e(e.toString());
+```
+
+**Correct (comprehensive context):**
+
+```dart
+final stopwatch = Stopwatch()..start();
+
+try {
+  await processOrder(order);
+} catch (e, st) {
+  logger.e(
+    'Failed to process order - '
+    'orderId=${order.id}, userId=${user.id}, '
+    'itemCount=${order.items.length}, total=${order.total}, '
+    'processingTimeMs=${stopwatch.elapsedMilliseconds}',
+    error: e,
+    stackTrace: st,
+  );
+  rethrow;
+}
+```
+
+**Essential context to include:**
+- Error object and stack trace (`error:`, `stackTrace:`)
+- Entity identifiers (orderId, userId, etc.)
+- Input that caused the issue (item count, amounts)
+- Timing information (`elapsedMilliseconds`)
+- Device/session context where applicable (Flutter)
+
+**Flutter-specific context:**
+
+```dart
+try {
+  await submitForm(formData);
+} catch (e, st) {
+  logger.e(
+    'Form submission failed - '
+    'screen=${ModalRoute.of(context)?.settings.name}, '
+    'userId=${authProvider.userId}',
+    error: e,
+    stackTrace: st,
+  );
+}
+```
+
+**Tools:** logger package, Code Review

package/skill-assets/sunlint-code-quality/rules/dart/C041-no-hardcoded-secrets.md

@@ -0,0 +1,75 @@
+---
+title: No Hardcoded Secrets
+impact: HIGH
+impactDescription: prevents credential leakage from source code
+tags: security, secrets, credentials, api-keys, quality
+---
+
+## No Hardcoded Secrets
+
+Secrets hardcoded in source code will be exposed in version control, app binaries, and decompilation.
+
+**Incorrect (hardcoded secrets):**
+
+```dart
+// BAD: Hardcoded API key in source code
+const apiKey = 'sk_live_abc123xyz456';
+const dbPassword = 'MySecretP@ss!';
+const jwtSecret = 'super-secret-jwt-key';
+const stripeKey = 'pk_live_51Abc...';
+```
+
+**Correct (externalized secrets - Flutter):**
+
+```dart
+// Option 1: dart-define at build time (recommended for CI/CD)
+// Run: flutter build apk --dart-define=API_KEY=sk_live_xxx
+const apiKey = String.fromEnvironment('API_KEY');
+const apiUrl = String.fromEnvironment('API_URL', defaultValue: 'https://api.dev.example.com');
+
+// Option 2: flutter_secure_storage for runtime secrets
+import 'package:flutter_secure_storage/flutter_secure_storage.dart';
+
+class SecretRepository {
+  final _storage = const FlutterSecureStorage();
+
+  Future<String?> getApiKey() => _storage.read(key: 'api_key');
+  Future<void> saveApiKey(String key) => _storage.write(key: 'api_key', value: key);
+}
+
+// Option 3: Remote config (Firebase Remote Config)
+final remoteConfig = FirebaseRemoteConfig.instance;
+final featureFlag = remoteConfig.getBool('new_feature_enabled');
+```
+
+**For .env files (development only):**
+
+```dart
+// pubspec.yaml - add envied package
+// dev_dependencies:
+//   envied_generator: ^0.5.0
+
+// lib/config/env.dart
+import 'package:envied/envied.dart';
+part 'env.g.dart';
+
+@Envied(path: '.env')
+abstract class Env {
+  @EnviedField(varName: 'API_KEY', obfuscate: true)
+  static final String apiKey = _Env.apiKey;
+}
+```
+
+**Never commit:**
+
+```gitignore
+# .gitignore
+.env
+.env.*
+*.keystore
+*.jks
+google-services.json    # Contains API keys
+GoogleService-Info.plist
+```
+
+**Tools:** GitLeaks, git-secrets, flutter_secure_storage, envied

package/skill-assets/sunlint-code-quality/rules/dart/C042-boolean-naming.md

@@ -0,0 +1,73 @@
+---
+title: Boolean Names Is/Has/Should
+impact: HIGH
+impactDescription: makes conditions instantly readable
+tags: naming, booleans, readability, quality
+---
+
+## Boolean Names Is/Has/Should
+
+Boolean variable prefixes make conditions instantly readable.
+
+**Incorrect (unclear boolean variable names):**
+
+```dart
+final active = user.status == 'active';
+final admin = checkAdminRole(user);
+final items = cart.isNotEmpty;
+final update = needsRefresh();
+```
+
+**Correct (boolean prefixes for variables):**
+
+```dart
+final isActive = user.status == 'active';
+final isAdmin = checkAdminRole(user);
+final hasItems = cart.isNotEmpty;
+final shouldUpdate = needsRefresh();
+final canEdit = hasPermission(user, 'edit');
+final willExpire = expirationDate.isBefore(tomorrow);
+```
+
+**Boolean prefixes:**
+
+| Prefix | Use For |
+|--------|---------|
+| `is` | State (isActive, isEnabled, isLoading) |
+| `has` | Ownership (hasPermission, hasError, hasItems) |
+| `should` | Decision (shouldUpdate, shouldRetry) |
+| `can` | Capability (canEdit, canDelete, canSubmit) |
+| `will` | Future (willExpire, willRetry) |
+
+**In Flutter widgets:**
+
+```dart
+class OrderCard extends StatelessWidget {
+  const OrderCard({
+    super.key,
+    required this.order,
+    required this.isSelected,
+    required this.canCancel,
+    required this.onTap,
+  });
+
+  final Order order;
+  final bool isSelected;
+  final bool canCancel;
+  final VoidCallback onTap;
+
+  @override
+  Widget build(BuildContext context) {
+    return Card(
+      color: isSelected ? Colors.blue[100] : Colors.white,
+      child: ListTile(
+        title: Text(order.id),
+        trailing: canCancel ? CancelButton(order: order) : null,
+        onTap: onTap,
+      ),
+    );
+  }
+}
+```
+
+**Tools:** Code Review, dart_analyzer

package/skill-assets/sunlint-code-quality/rules/dart/C052-widget-parsing.md

@@ -0,0 +1,84 @@
+---
+title: Separate Parsing From Widgets And Controllers
+impact: HIGH
+impactDescription: keeps widgets/controllers thin and focused
+tags: widget, controller, parsing, transformation, patterns, quality
+---
+
+## Separate Parsing From Widgets And Controllers
+
+Widgets and controllers should be thin — only handling UI/flow concerns. Data transformation logic should be extracted into mappers or presenters.
+
+**Incorrect (transformation in widget/controller):**
+
+```dart
+class UserProfilePage extends StatelessWidget {
+  const UserProfilePage({super.key, required this.user});
+  final User user;
+
+  @override
+  Widget build(BuildContext context) {
+    // Transformation logic inside widget
+    final fullName = '${user.firstName} ${user.lastName}';
+    final email = user.email.toLowerCase();
+    final createdAt = DateFormat('yyyy-MM-dd').format(user.createdAt);
+    final age = DateTime.now().difference(user.birthDate).inDays ~/ 365;
+    final avatarUrl = 'https://cdn.example.com/avatars/${user.id}.jpg';
+
+    return Column(
+      children: [
+        Text(fullName),
+        Text(email),
+        Text('Joined: $createdAt'),
+        Text('Age: $age'),
+        Image.network(avatarUrl),
+      ],
+    );
+  }
+}
+```
+
+**Correct (separate mapper/presenter):**
+
+```dart
+// Presenter / ViewModel
+class UserProfilePresenter {
+  UserProfilePresenter(this._user);
+  final User _user;
+
+  String get fullName => '${_user.firstName} ${_user.lastName}';
+  String get email => _user.email.toLowerCase();
+  String get joinedDate => DateFormat('yyyy-MM-dd').format(_user.createdAt);
+  int get age => DateTime.now().difference(_user.birthDate).inDays ~/ 365;
+  String get avatarUrl => 'https://cdn.example.com/avatars/${_user.id}.jpg';
+}
+
+// Thin widget
+class UserProfilePage extends StatelessWidget {
+  const UserProfilePage({super.key, required this.user});
+  final User user;
+
+  @override
+  Widget build(BuildContext context) {
+    final presenter = UserProfilePresenter(user);
+
+    return Column(
+      children: [
+        Text(presenter.fullName),
+        Text(presenter.email),
+        Text('Joined: ${presenter.joinedDate}'),
+        Text('Age: ${presenter.age}'),
+        Image.network(presenter.avatarUrl),
+      ],
+    );
+  }
+}
+```
+
+**Benefits:**
+- Reusable transformation logic
+- Testable presenters/mappers
+- Clean, readable widgets
+- Consistent display format
+
+**Tools:** Code Review, Architecture Review