Dart Rules

---
name: dart-rules
description: "Dart/Flutter coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .dart, pubspec.yaml, Flutter, Riverpod, Bloc, widget, StatelessWidget, StatefulWidget. Load when writing, reviewing, or editing Dart/Flutter code."
effort: medium
user-invocable: false
allowed-tools: Read
---

# Dart/Flutter Rules

These rules come from `app/rules/dart/` in ai-toolkit. They cover
the project's standards for coding style, frameworks, patterns,
security, and testing in Dart/Flutter. Apply them when writing or
reviewing Dart/Flutter code.

# Dart Coding Style

## Naming
- PascalCase: classes, enums, typedefs, extensions, mixins.
- camelCase: variables, functions, methods, parameters, named constants.
- snake_case: libraries, packages, directories, source files.
- UPPER_SNAKE: not used in Dart. Use camelCase for constants.
- Prefix private members with `_`: `_internalState`, `_helper()`.

## Null Safety
- Enable sound null safety (default since Dart 2.12).
- Use `?` types only when null is semantically meaningful.
- Use `!` operator sparingly. Prefer null checks or `??` fallback.
- Use `late` keyword only when initialization is guaranteed before access.
- Use `required` keyword for mandatory named parameters.

## Classes
- Use `const` constructors for immutable classes.
- Use factory constructors for caching, subtype selection, or validation.
- Use named constructors for clarity: `Point.fromJson(json)`.
- Use `final` fields for immutable properties.
- Use `@immutable` annotation on classes that should be immutable.

## Functions
- Use named parameters for functions with >2 parameters.
- Use `required` for mandatory named parameters.
- Use default values for optional parameters.
- Use fat arrow (`=>`) for single-expression functions.
- Always specify return types for public functions.

## Collections
- Use collection literals: `[]`, `{}`, `<String, int>{}`.
- Use `if` and `for` inside collection literals for conditional/iterative building.
- Use spread operator: `[...list1, ...list2]`.
- Use `whereType<T>()` for type-safe filtering.
- Prefer `const` collections when values are known at compile time.

## Async
- Use `async`/`await` for all asynchronous operations.
- Return `Future<T>` from async functions. Never return `void`.
- Use `Stream<T>` for continuous data (events, real-time updates).
- Use `Future.wait()` for concurrent independent operations.
- Use `Completer<T>` only when wrapping callback-based APIs.

## Imports
- Order: `dart:` SDK, `package:` external, relative project imports.
- Use `show`/`hide` to limit import scope when names conflict.
- Use `as` prefix for namespace conflicts: `import 'package:foo/foo.dart' as foo`.
- Prefer relative imports within the same package.

## Formatting
- Use `dart format` (line length 80) for consistent formatting.
- Use `dart analyze` for static analysis with default lint rules.
- Use `analysis_options.yaml` with recommended lints: `flutter_lints` or `lints`.
- Use trailing commas in multi-line argument lists for cleaner diffs.

# Dart Frameworks

## Flutter
- Use `StatelessWidget` by default. Use `StatefulWidget` only for local state.
- Use `const` constructors and `const` widgets for build optimization.
- Use `Key` parameters for widgets in lists for correct diffing.
- Extract large `build()` methods into smaller widget classes (not methods).
- Use `Theme.of(context)` and `TextTheme` for consistent styling.

## Navigation
- Use `GoRouter` for declarative, type-safe routing.
- Define routes as constants: `static const String home = '/home'`.
- Use `ShellRoute` for persistent navigation bars across routes.
- Use `context.go()` for navigation, `context.push()` for stacking.
- Pass arguments via path parameters or `extra` for complex objects.

## Networking
- Use `dio` for HTTP with interceptors, retry, and cancellation.
- Use `retrofit` (code gen) for type-safe REST client definitions.
- Use interceptors for auth token injection and refresh logic.
- Set timeouts on every request: `connectTimeout`, `receiveTimeout`.
- Use `CancelToken` for cancelling in-flight requests on navigation.

## JSON Serialization
- Use `json_serializable` (+ `build_runner`) for generated `fromJson`/`toJson`. Default `fieldRename: FieldRename.none` uses Dart property names as-is — combined with Effective Dart `lowerCamelCase`, this produces `camelCase` JSON keys with zero configuration.
- Flutter docs recommend: *"best if both server and client follow the same naming strategy"* ([Flutter — JSON and serialization](https://docs.flutter.dev/data-and-backend/serialization/json)). When they do, no mapping is needed.
- When server uses a different convention, prefer `@JsonSerializable(fieldRename: FieldRename.snake)` at the class level (or globally in `build.yaml`) over sprinkling `@JsonKey(name:)` on every field. Community recommendation from the `json_serializable` docs and pub.dev guides.
- Use individual `@JsonKey(name: '...')` only for exceptional cases: external API with mixed conventions, reserved Dart keyword collision (`class`, `is`, `new`), or legacy field rename during deprecation window. Document the reason in a comment.
- For enum / status / permission values on the wire: `UPPER_SNAKE_CASE` is the cross-language community consensus (see `common/coding-style.md` — JSON Wire Format Conventions). Dart enum case names themselves stay `lowerCamelCase` per Effective Dart; map them to uppercase strings in `fromJson`/`toJson` (`value.toUpperCase()` + `switch`).
- Write unit tests asserting both directions (`fromJson` + `toJson`) with explicit expected keys. Catches contract drift at CI time.

## Local Storage
- Use `shared_preferences` for simple key-value persistence.
- Use `drift` (formerly Moor) for type-safe SQLite with reactive queries.
- Use `hive` for fast, lightweight NoSQL local storage.
- Use `flutter_secure_storage` for sensitive data (tokens, passwords).
- Never store secrets in `shared_preferences` (not encrypted).

## Dependency Injection
- Use `get_it` for service locator pattern. Register at app startup.
- Use `injectable` (code gen) for automatic registration from annotations.
- Use Riverpod providers as DI containers for testable architecture.
- Register singletons for services, factories for per-use instances.

## Platform Channels
- Use `MethodChannel` for invoking native (iOS/Android) code.
- Use `EventChannel` for streaming data from native to Dart.
- Use `Pigeon` (code gen) for type-safe platform channel definitions.
- Handle `MissingPluginException` gracefully on unsupported platforms.

## Testing Frameworks
- Use `flutter_test` for widget tests with `WidgetTester`.
- Use `integration_test` package for full app integration tests.
- Use `patrol` for native-aware integration testing (permissions, notifications).
- Use `golden_toolkit` for advanced visual regression testing.

## Build and CI
- Use `flutter build` with `--release` and `--dart-define` for env configuration.
- Use flavors (`--flavor`) for dev/staging/prod build variants.
- Use `flutter analyze` in CI for static analysis enforcement.
- Use `flutter test --coverage` with `lcov` for coverage reporting.

# Dart Patterns

## Error Handling
- Use typed exceptions for domain errors: `class UserNotFoundException implements Exception`.
- Use `try-catch` with specific exception types. Avoid bare `catch (e)`.
- Use `rethrow` to preserve stack trace when re-raising exceptions.
- Use `Result<T, E>` pattern (e.g., `dartz` Either) for expected failures.
- Use `Future.catchError()` only when `async/await` is not applicable.

## State Management (Flutter)
- Use Riverpod for compile-safe, testable state management.
- Use BLoC pattern for event-driven state with clear input/output.
- Use `ChangeNotifier` / `ValueNotifier` for simple local state.
- Use `StateNotifier` (Riverpod) for immutable state transitions.
- Keep state classes immutable. Use `copyWith()` for updates.

## Riverpod
- Use `@riverpod` annotation (code gen) for provider definitions.
- Use `ref.watch()` for reactive dependencies. Use `ref.read()` for one-time access.
- Use `AsyncNotifier` for async state management.
- Use `autoDispose` for providers that should clean up when unused.
- Use `family` modifier for parameterized providers.

## BLoC Pattern
- Separate events (input), states (output), and logic (bloc).
- Use `sealed class` for events and states (exhaustive `switch`).
- Use `Emitter<State>` for emitting state transitions.
- Use `transformEvents()` for debouncing search inputs.
- Use `BlocObserver` for global logging and error tracking.

## Repository Pattern
- Abstract data sources behind repository interfaces.
- Repositories return domain models, not DTOs or raw data.
- Use `Future<T>` for single values, `Stream<T>` for real-time updates.
- Cache data in repository layer when appropriate.
- Inject repositories via constructor. Use Riverpod/GetIt for DI.

## Freezed (Code Generation)
- Use `@freezed` for immutable data classes with `copyWith`, equality, `toString`.
- Use `@freezed` sealed unions for state modeling: `factory State.loading()`.
- Use `when()` / `map()` for exhaustive pattern matching on freezed unions.
- Run `dart run build_runner build` after modifying freezed classes.

## Async Patterns
- Use `Stream.asyncMap()` for transforming streams with async operations.
- Use `StreamController<T>` for custom streams. Close in `dispose()`.
- Use `Completer<T>` to bridge callback APIs to Future-based APIs.
- Use `Timer.periodic()` for polling. Cancel in `dispose()`.
- Use `compute()` (Flutter) for CPU-intensive work on isolates.

## Anti-Patterns
- Using `dynamic` type: defeats type safety. Use `Object?` or generics.
- Not disposing controllers/subscriptions: causes memory leaks.
- Putting business logic in widgets: extract to services/blocs.
- Using `setState()` for global state: use proper state management.
- Deep widget nesting: extract sub-widgets as separate classes.

# Dart Security

## Input Validation
- Validate all user input in form fields with `TextFormField` validators.
- Use `RegExp` for pattern validation (email, phone, URL).
- Sanitize HTML content before rendering. Never use `Html` widget with raw user input.
- Validate deep link parameters before navigation or data loading.
- Limit text input length with `maxLength` on `TextFormField`.

## Network Security
- Use HTTPS exclusively. Configure `SecurityContext` for certificate pinning.
- Use `dio` interceptors for consistent auth header injection.
- Validate SSL certificates in production. Do not disable certificate checks.
- Set connection and read timeouts on all HTTP requests.
- Use `CancelToken` to abort requests when the user navigates away.

## Data Storage
- Use `flutter_secure_storage` for tokens, passwords, and API keys.
- Never store sensitive data in `shared_preferences` (stored in plaintext).
- Encrypt local databases (`drift` with `sqlcipher`, or `hive` with encryption).
- Clear secure storage on user logout.
- Use `kIsWeb` checks to handle web platform storage limitations.

## Authentication
- Use OAuth 2.0 / OIDC with PKCE flow for mobile authentication.
- Store refresh tokens in secure storage. Store access tokens in memory.
- Use `flutter_appauth` for standards-compliant OAuth flows.
- Implement biometric authentication with `local_auth` package.
- Never store credentials in Dart source code or asset files.

## Platform Channel Security
- Validate all data received from native code via platform channels.
- Do not pass sensitive data through `MethodChannel` logging-enabled calls.
- Use `Pigeon` for type-safe channel communication (prevents mismatched types).
- Handle `PlatformException` gracefully for missing native implementations.

## Obfuscation and Hardening
- Use `--obfuscate --split-debug-info=<dir>` for release builds.
- Use `--dart-define` for environment-specific configuration (not secrets).
- Do not embed API keys in the Dart source. Use server-side proxying.
- Use ProGuard rules (Android) and symbol stripping (iOS) for native code.

## WebView Security
- Use `webview_flutter` with JavaScript disabled unless explicitly needed.
- Restrict navigation to allowlisted domains with `NavigationDelegate`.
- Sanitize any data passed from WebView to Dart via JavaScript channels.
- Do not load untrusted URLs in WebViews.

## Dependency Security
- Run `dart pub outdated` regularly. Update dependencies promptly.
- Audit `pubspec.lock` for unexpected transitive dependencies.
- Use `dart pub audit` (when available) for vulnerability scanning.
- Prefer well-maintained packages with high pub.dev scores.
- Pin exact versions in `pubspec.yaml` for production apps.

# Dart Testing

## Framework
- Use `package:test` for pure Dart unit tests.
- Use `package:flutter_test` for Flutter widget and integration tests.
- Use `package:mockito` with `@GenerateMocks` for mock generation.
- Use `package:mocktail` as a simpler alternative (no code generation).

## File Naming
- Test files: `foo_test.dart` in `test/` mirroring `lib/` structure.
- Widget tests: `test/widgets/` for Flutter widget tests.
- Integration tests: `integration_test/` directory (Flutter convention).
- Golden tests: `test/goldens/` for visual regression snapshots.

## Structure
- Use `group()` for organizing related tests.
- Use `setUp()` / `tearDown()` for per-test setup and cleanup.
- Use `setUpAll()` / `tearDownAll()` for expensive one-time setup.
- Name tests descriptively: `test('returns null when user is not found', ...)`.

## Assertions
- Use `expect(actual, matcher)` with built-in matchers.
- Use `equals()`, `isNull`, `isNotNull`, `isA<T>()` for type/value checks.
- Use `throwsA(isA<FormatException>())` for exception testing.
- Use `completion(expected)` for Future assertions.
- Use `emitsInOrder([...])` for Stream emission testing.

## Mocking (Mockito)
- Annotate: `@GenerateMocks([UserRepository])`. Run `build_runner`.
- Stub: `when(mock.getUser(any)).thenAnswer((_) async => user)`.
- Verify: `verify(mock.saveUser(captureAny)).called(1)`.
- Use `verifyNever()` to assert a method was not called.
- Use `throwOnMissingStub()` to catch unstubbed method calls.

## Widget Testing (Flutter)
- Use `testWidgets('description', (tester) async { ... })`.
- Use `tester.pumpWidget(MaterialApp(home: MyWidget()))` to render.
- Use `tester.pump()` to trigger rebuilds after state changes.
- Use `tester.pumpAndSettle()` to wait for animations to complete.
- Use `find.byType()`, `find.text()`, `find.byKey()` for widget lookups.
- Use `tester.tap()`, `tester.enterText()` for interaction simulation.

## Golden Tests
- Use `matchesGoldenFile('goldens/my_widget.png')` for visual comparison.
- Run `flutter test --update-goldens` to regenerate baseline images.
- Use golden tests for complex UI components, not simple widgets.
- Keep golden tests platform-specific (render output varies by OS).

## Best Practices
- Test public API behavior, not implementation details.
- Use `fake` classes (implementing interfaces) for simple test doubles.
- Use `addTearDown()` to register cleanup in the test body.
- Run `flutter test --coverage` and check `coverage/lcov.info`.
- Use `blocTest()` from `bloc_test` package for BLoC testing.