@ngxtm/devkit 3.3.0 → 3.4.1

package/rules/flutter/riverpod.rule.md

@@ -0,0 +1,78 @@
+---
+id: flutter-riverpod
+version: 1.0.0
+triggers: [riverpod, provider, state]
+---
+
+# Riverpod
+
+State management with Riverpod 2.x and code generation.
+
+## Setup
+
+```yaml
+dependencies:
+  flutter_riverpod: ^2.4.0
+  riverpod_annotation: ^2.3.0
+
+dev_dependencies:
+  riverpod_generator: ^2.3.0
+  build_runner: ^2.4.0
+```
+
+## Provider Types
+
+```dart
+// Simple value
+@riverpod
+String greeting(GreetingRef ref) => 'Hello';
+
+// Async data
+@riverpod
+Future<User> user(UserRef ref) async {
+  return ref.watch(apiProvider).getUser();
+}
+
+// Notifier for mutable state
+@riverpod
+class Counter extends _$Counter {
+  @override
+  int build() => 0;
+
+  void increment() => state++;
+}
+```
+
+## Consumer Usage
+
+```dart
+class MyWidget extends ConsumerWidget {
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final count = ref.watch(counterProvider);
+    return Text('$count');
+  }
+}
+```
+
+## Async Handling
+
+```dart
+ref.watch(userProvider).when(
+  data: (user) => UserCard(user),
+  loading: () => const CircularProgressIndicator(),
+  error: (e, st) => ErrorText(e.toString()),
+);
+```
+
+## Family Providers
+
+```dart
+@riverpod
+Future<Post> post(PostRef ref, int id) async {
+  return ref.watch(apiProvider).getPost(id);
+}
+
+// Usage
+ref.watch(postProvider(42));
+```

package/rules/flutter/security/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: Flutter Security
+description: Security standards for Flutter applications based on OWASP Mobile.
+metadata:
+  labels: [security, owasp, pii, encryption]
+  triggers:
+    files: ['lib/infrastructure/**', 'pubspec.yaml']
+    keywords: [secure_storage, obfuscate, jailbreak, pinning, PII, OWASP]
+---
+
+# Mobile Security
+
+## **Priority: P0 (CRITICAL)**
+
+Standards for basic mobile security and PII protection.
+
+## Implementation Guidelines
+
+- **Secure Storage**: Use `flutter_secure_storage` for tokens/PII. Never use `shared_preferences`.
+- **Hardcoding**: Never store API keys or secrets in Dart code. Use `--dart-define` or `.env`.
+- **Obfuscation**: Always release with `--obfuscate` and `--split-debug-info`.
+- **SSL Pinning**: For high-security apps, use `dio_certificate_pinning`.
+- **Root Detection**: Use `flutter_jailbreak_detection` for financial/sensitive applications.
+- **PII Masking**: Mask sensitive data (email, phone) in logs and analytics.
+
+## Reference & Examples
+
+For SSL Pinning and Secure Storage implementation details:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+layer-based-clean-architecture | performance

package/rules/flutter/security/references/REFERENCE.md

@@ -0,0 +1,15 @@
+# Mobile Security Reference
+
+Detailed implementation patterns for OWASP Mobile compliance.
+
+## References
+
+- [**Network Security**](network-security.md) - SSL Pinning and Security Headers.
+- [**Secure Storage**](secure-storage-impl.md) - PII and Token management.
+
+## **CI/CD Security Flag**
+
+```bash
+# Obfuscation during build
+flutter build apk --obfuscate --split-debug-info=./debug-info
+```

package/rules/flutter/security/references/network-security.md

@@ -0,0 +1,28 @@
+# Network Security & Certificate Pinning
+
+## **SSL Pinning with Dio**
+
+```dart
+import 'package:dio/dio.dart';
+import 'package:dio_certificate_pinning/dio_certificate_pinning.dart';
+
+final dio = Dio();
+dio.interceptors.add(CertificatePinningInterceptor(
+  allowedSHAFingerprints: [
+    "70:99:27:8B:54:4A:40:F5:30:DB:73:E3:64:36:0F:70:3D:09:A6:49",
+  ],
+));
+```
+
+## **Security Headers Interceptor**
+
+```dart
+class SecurityInterceptor extends Interceptor {
+  @override
+  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
+    options.headers['X-Content-Type-Options'] = 'nosniff';
+    options.headers['X-Frame-Options'] = 'DENY';
+    super.onRequest(options, handler);
+  }
+}
+```

package/rules/flutter/testing/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: Flutter Testing Standards
+description: Unit, widget, and integration testing using mocktail and bloc_test.
+metadata:
+  labels: [testing, junit, mocktail, bloc_test, golden-tests]
+  triggers:
+    files: ['**/test/**.dart']
+    keywords: [test, group, expect, mocktail, blocTest, when, any]
+---
+
+# Testing Standards
+
+## **Priority: P1 (HIGH)**
+
+Ensuring code reliability through multi-layered testing strategies.
+
+## Structure
+
+```text
+test/
+├── unit/ # Business logic & mapping (Blocs, Repositories, UseCases)
+├── widget/ # UI component behavior (Screens, Widgets)
+└── integration/ # End-to-end flows
+```
+
+## Implementation Guidelines
+
+- **Testing Pyramid**: Maintain ~70% Unit Tests, ~20% Widget Tests, ~10% Integration Tests.
+- **Mocks**: Use `mocktail` for type-safe, boilerplate-free mocking.
+- **Unit Tests**: Test logic in isolation. Verify all edge cases (Success, Failure, Exception).
+- **Widget Tests**: Test high-value interactions (Button clicks, Error states, Loading indicators).
+- **BLoC Tests**: Use `blocTest` to verify state emission sequences.
+- **Code Coverage**: Aim for 80%+ coverage on Domain and Presentation (Logic) layers.
+
+## Deep Dive References
+
+- [Unit Testing Strategies](./references/unit-testing.md) (Test Data Builders, Mocktail)
+- [Widget Testing Strategies](./references/widget-testing.md) (Robot Pattern)
+- [Integration Testing](./references/integration-testing.md) (Shared Robots, Real Device)
+- [Robot Pattern Implementation](./references/robot-pattern.md)
+
+## Related Topics
+
+layer-based-clean-architecture | dependency-injection | cicd

package/rules/flutter/testing/references/REFERENCE.md

@@ -0,0 +1,21 @@
+# Testing Standards Reference
+
+Practical patterns for Unit, Widget, and Golden tests.
+
+## References
+
+- [**Unit Testing**](unit-testing.md) - Mocking, AAA pattern, Repository testing.
+- [**Widget Testing**](widget-testing.md) - UI interactions, Finders, Pumping frames.
+- [**BLoC Testing**](bloc-testing.md) - Using `blocTest` for state transitions.
+
+## **Quick Assertions**
+
+```dart
+// Mocktail Stub
+when(() => repository.fetchData()).thenAnswer((_) async => right(data));
+
+// Expect Matchers
+expect(state.isLoading, isTrue);
+expect(find.text('Hello'), findsOneWidget);
+verify(() => repository.fetchData()).called(1);
+```

package/rules/flutter/testing/references/bloc-testing.md

@@ -0,0 +1,38 @@
+# BLoC Testing with `bloc_test`
+
+`blocTest` ensures your events trigger the correct sequence of states.
+
+## **Success Scenario**
+
+```dart
+blocTest<AuthBloc, AuthState>(
+  'emits [loading, authenticated] when login is successful',
+  build: () {
+    // Stub the repository
+    when(() => mockAuthRepo.login(any(), any()))
+        .thenAnswer((_) async => Right(mockUser));
+    return AuthBloc(mockAuthRepo);
+  },
+  act: (bloc) => bloc.add(const AuthEvent.loginPressed('test@email.com', 'pass123')),
+  expect: () => [
+    const AuthState.loading(),
+    AuthState.authenticated(mockUser),
+  ],
+  verify: (_) {
+    verify(() => mockAuthRepo.login('test@email.com', 'pass123')).called(1);
+  },
+);
+```
+
+## **Best Practices & Pitfalls**
+
+- **Do not mock based on State**: Do not use values in the BLoC state to mock data or verify calls. This is unreliable because it tracks the number of times a state is emitted (which can happen multiple times) rather than verifying the actual event trigger. Always verify the downstream Dependency/Service call in the `verify` block.
+- **Initial State verification**
+
+Always ensure your BLoC doesn't emit anything just by being created unless specified.
+
+```dart
+test('initial state is AuthState.initial', () {
+  expect(AuthBloc(mockRepo).state, const AuthState.initial());
+});
+```

package/rules/flutter/testing/references/integration-testing.md

@@ -0,0 +1,128 @@
+# Advanced Integration Testing
+
+Expert strategies for running "hard" tests (Native, Network, Time) reliably on CI.
+
+## The Core Problem
+
+Standard flutter `integration_test` struggles with:
+
+1. **Native UI**: Permission dialogs, Notifications, Dark Mode toggles.
+2. **WebViews**: Logging in via 3rd party identity providers.
+3. **Flakiness**: `pumpAndSettle` hanging on infinite animations.
+
+## Recommended Tool: Patrol
+
+[Patrol](https://pub.dev/packages/patrol) extends Flutter's testing capabilities to interact with the OS.
+
+### Why Patrol?
+
+- **Native Interactions**: `$.native.tap()` to query OS/native views.
+- **Improved Finders**: `$(#email)` instead of `find.byKey(Key('email'))`.
+- **Better Waiters**: `waitUntilVisible()` handles spinners correctly (unlike `pumpAndSettle`).
+
+### Setup
+
+1. Add dependency: `dev_dependencies: patrol: ^3.0.0`
+2. Create test file: `integration_test/app_test.dart`
+
+```dart
+import 'package:patrol/patrol.dart';
+
+void main() {
+  patrolTest(
+    'Login and accept permissions',
+    nativeAutomation: true, // Enable native controls
+    ($) async {
+      await $.pumpWidgetAndSettle(MyApp());
+
+      // 1. Flutter Interaction (Concise Syntax)
+      await $(#emailField).enterText('user@test.com');
+      await $(#passwordField).enterText('password123');
+      await $('Login').tap();
+
+      // 2. Native Interaction (The Killer Feature)
+      if (await $.native.isPermissionDialogVisible()) {
+        await $.native.grantPermissionWhenInUse();
+      }
+
+      // 3. WebViews (if needed)
+      // await $.native.tap(Selector(text: 'Accept Cookies'));
+    },
+  );
+}
+```
+
+## Strategy 1: Real Environment (End-to-End)
+
+Run tests against a real staging/dev backend to verify the full system. Do **not** mock the HTTP client in Integration Tests unless strictly necessary for hermeticity.
+
+```bash
+# Run with Patrol
+patrol test -t integration_test/app_test.dart --dart-define=ENV=staging
+```
+
+```dart
+// main.dart
+void main() {
+  final env = String.fromEnvironment('ENV', defaultValue: 'prod');
+  runApp(MyApp(config: Config.fromEnv(env)));
+}
+```
+
+## Strategy 2: Robust Waiters
+
+Avoid `pumpAndSettle()` for any screen with a `CircularProgressIndicator` or Lottie animation, as it will timeout waiting for the "animation" to settle.
+
+**Use Patrol's `waitUntilVisible`**:
+
+```dart
+// BAD
+// await $.pumpAndSettle(); // Times out if a spinner is running
+
+// GOOD
+await $('Welcome Home').waitUntilVisible(timeout: Duration(seconds: 10));
+```
+
+**Legacy (If not using Patrol)**:
+You must write a custom extension to pump frames manually.
+
+```dart
+extension PumpUntilFound on WidgetTester {
+  Future<void> pumpUntilFound(Finder finder) async {
+    while (!any(finder)) {
+      await pump(const Duration(milliseconds: 100));
+    }
+  }
+}
+```
+
+## Strategy 3: Handling Long Delays
+
+For flows involving long waits (e.g., "Verification code expires in 5 minutes"), waiting real time is impractical.
+
+**Approach**: Configure the app to use shorter durations in non-production environments.
+
+```dart
+// Code
+class TimerWidget extends StatelessWidget {
+  final Duration duration; // Configurable
+  const TimerWidget({this.duration = const Duration(minutes: 5)});
+}
+
+// Test
+await $.pumpWidget(TimerWidget(duration: Duration(seconds: 1)));
+await $('Resend Code').waitUntilVisible(); // Done instantly
+```
+
+## Strategy 4: Debugging Failures
+
+Patrol automatically handles taking screenshots on failure if configured, but you can also do it manually.
+
+```dart
+// Patrol automatically captures screenshots on failure in `patrol test` output.
+// No boilerplate needed.
+```
+
+## Related Topics
+
+[Robot Pattern](./robot-pattern.md) | [Github Actions](../../cicd/references/github-actions.md)

package/rules/flutter/testing/references/robot-pattern.md

@@ -0,0 +1,82 @@
+# Robot Pattern (Page Object Model)
+
+For maintainable widget and integration tests, decouple the "what" (business logic/asserts) from the "how" (finding widgets).
+
+## Why?
+
+- **Readability**: Tests read like user stories.
+- **Reusability**: One Robot works for both **Widget Tests** and **Integration Tests** (shared API).
+- **Resilience**: If a widget key changes, you update only the Robot, not 50 tests.
+
+## Directory Structure
+
+Place robots in `test/robots/` so they can be imported by `test/widget/` and `integration_test/` folders.
+
+```text
+test/
+  robots/
+    login_robot.dart
+  widget/
+    login_test.dart
+integration_test/
+  full_app_test.dart
+```
+
+## Example
+
+### The Robot Class (`test/robots/login_robot.dart`)
+
+```dart
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+class LoginRobot {
+  final WidgetTester tester;
+
+  LoginRobot(this.tester);
+
+  // Finders (Private)
+  final _emailField = find.byKey(const Key('emailKey'));
+  final _passwordField = find.byKey(const Key('passwordKey'));
+  final _loginButton = find.byType(ElevatedButton);
+
+  // Actions
+  Future<void> enterEmail(String email) async {
+    await tester.enterText(_emailField, email);
+    await tester.pump();
+  }
+
+  Future<void> enterPassword(String password) async {
+    await tester.enterText(_passwordField, password);
+    await tester.pump();
+  }
+
+  Future<void> tapLogin() async {
+    await tester.tap(_loginButton);
+    await tester.pumpAndSettle();
+  }
+
+  // Assertions
+  void expectErrorShown() {
+    expect(find.text('Invalid credentials'), findsOneWidget);
+  }
+}
+```
+
+### The Test (`test/widget/login_screen_test.dart`)
+
+```dart
+testWidgets('Login failure flow', (tester) async {
+  // 1. Init
+  await tester.pumpWidget(myApp());
+  final robot = LoginRobot(tester);
+
+  // 2. Interact (Readable DSL)
+  await robot.enterEmail('bad@email.com');
+  await robot.enterPassword('wrong');
+  await robot.tapLogin();
+
+  // 3. Verify
+  robot.expectErrorShown();
+});
+```

package/rules/flutter/testing/references/unit-testing.md

@@ -0,0 +1,130 @@
+# Unit Testing Strategies
+
+Unit tests verify the smallest parts of your application (functions, methods, classes) in isolation.
+
+## Core Rules
+
+1. **Isolation**: External dependencies (API, Database, SharedPreferences) **must** be mocked.
+2. **Scope**: One test file per source file (e.g., `user_repository.dart` -> `user_repository_test.dart`).
+3. **Arrange-Act-Assert (AAA)**: Follow this structure strictly.
+
+## Advanced Techniques
+
+### 1. Test Data Builders
+
+Avoid hardcoding large objects in every test. Use a Builder pattern to generate valid default data with overrides.
+
+```dart
+class UserBuilder {
+  String _id = '1';
+  String _name = 'Default User';
+
+  UserBuilder withId(String id) {
+    _id = id;
+    return this;
+  }
+
+  User build() => User(id: _id, name: _name);
+}
+
+// Usage in test
+final user = UserBuilder().withId('99').build();
+```
+
+### 2. Mocking with Mocktail
+
+We prefer `mocktail` over `mockito` for its null-safety and simplicity.
+
+```dart
+import 'package:mocktail/mocktail.dart';
+import 'package:test/test.dart';
+
+// 1. Create Mock
+class MockUserRepository extends Mock implements UserRepository {}
+
+void main() {
+  late MockUserRepository mockRepo;
+  late GetUserProfileUseCase useCase;
+
+  setUp(() {
+    mockRepo = MockUserRepository();
+    useCase = GetUserProfileUseCase(mockRepo);
+
+    // Register fallback values if needed
+    registerFallbackValue(User.empty());
+  });
+
+  // 2. Test Group
+  group('GetUserProfileUseCase', () {
+    test('should return User when repository succeeds', () async {
+      // ARRANGE
+      final user = UserBuilder().build();
+      when(() => mockRepo.getUser('1')).thenAnswer((_) async => Right(user));
+
+      // ACT
+      final result = await useCase('1');
+
+      // ASSERT
+      expect(result, Right(user));
+      verify(() => mockRepo.getUser('1')).called(1);
+    });
+
+    test('should return Failure when repository fails', () async {
+      // ARRANGE
+      when(() => mockRepo.getUser(any())).thenThrow(ServerException());
+
+      // ACT
+      final call = useCase('1');
+
+      // ASSERT
+      expect(call, throwsA(isA<ServerException>()));
+    });
+  });
+}
+```
+
+## Best Practices & Anti-Patterns (DCM)
+
+Avoid common testing mistakes identified by Dart Code Metrics.
+
+### 1. Assertions are Mandatory
+
+Never write a test that just "runs" without verifying anything.
+
+```dart
+// BAD
+test('fetchUser runs', () async {
+  await repo.fetchUser();
+  // ❌ No assertion - test passes even if logic is broken
+});
+
+// GOOD
+test('fetchUser returns data', () async {
+  final result = await repo.fetchUser();
+  expect(result, isNotNull); // ✅ Always verify result
+});
+```
+
+### 2. Use Proper Matchers
+
+Use specific matchers for better error messages.
+
+```dart
+// BAD
+expect(list.length, 1); // Message: "Expected: <1> Actual: <0>"
+
+// GOOD
+expect(list, hasLength(1)); // Message: "Expected: list with length <1> Actual: list with length <0> [...]"
+```
+
+### 3. Async Expectations
+
+When testing Streams or Futures validation, use `expectLater` to ensure the test waits.
+
+```dart
+// BAD
+expect(stream, emits(1)); // Might finish test before stream emits
+
+// GOOD
+await expectLater(stream, emits(1));
+```