@aicgen/aicgen 1.0.0-beta.1 → 1.0.0

package/data/language/dart/error-handling.md

@@ -0,0 +1,355 @@
+# Error Handling in Dart
+
+## Custom Exceptions
+
+```dart
+// ✅ Create structured exception hierarchy
+class AppException implements Exception {
+  final String message;
+  final int? code;
+  final dynamic details;
+
+  AppException(this.message, {this.code, this.details});
+
+  @override
+  String toString() => 'AppException: $message (code: $code)';
+}
+
+class NotFoundException extends AppException {
+  NotFoundException(String resource, String id)
+      : super('$resource with id $id not found', code: 404);
+}
+
+class ValidationException extends AppException {
+  ValidationException(String message, {Map<String, String>? errors})
+      : super(message, code: 400, details: errors);
+}
+
+// Usage
+throw NotFoundException('User', userId);
+throw ValidationException('Invalid input', errors: {'email': 'Invalid format'});
+```
+
+## Try-Catch-Finally
+
+```dart
+// ✅ Catch specific exceptions first
+Future<User> fetchUser(String id) async {
+  try {
+    final response = await http.get('/api/users/$id');
+    return User.fromJson(response.data);
+  } on NetworkException catch (e) {
+    print('Network error: ${e.message}');
+    throw AppException('Network request failed', details: e);
+  } on FormatException catch (e) {
+    print('Invalid JSON: $e');
+    throw AppException('Invalid response format');
+  } catch (e, stackTrace) {
+    print('Unexpected error: $e');
+    print('Stack trace: $stackTrace');
+    rethrow;
+  } finally {
+    print('Request completed');
+  }
+}
+
+// ✅ Use finally for cleanup
+Future<void> processFile(String path) async {
+  File? file;
+  try {
+    file = File(path);
+    final content = await file.readAsString();
+    await processContent(content);
+  } catch (e) {
+    print('Error processing file: $e');
+    rethrow;
+  } finally {
+    // Always runs, even if exception thrown
+    await file?.close();
+  }
+}
+```
+
+## Result Type Pattern
+
+```dart
+// ✅ Explicit success/failure without exceptions
+class Result<T> {
+  final T? data;
+  final AppException? error;
+
+  const Result.success(T data) : data = data, error = null;
+  const Result.failure(AppException error) : data = null, error = error;
+
+  bool get isSuccess => error == null;
+  bool get isFailure => error != null;
+}
+
+// Usage
+Future<Result<User>> fetchUserSafe(String id) async {
+  try {
+    final user = await fetchUser(id);
+    return Result.success(user);
+  } on AppException catch (e) {
+    return Result.failure(e);
+  } catch (e) {
+    return Result.failure(AppException('Unknown error: $e'));
+  }
+}
+
+// Consumer handles explicitly
+final result = await fetchUserSafe('123');
+if (result.isSuccess) {
+  print('User: ${result.data!.name}');
+} else {
+  print('Error: ${result.error!.message}');
+}
+```
+
+## Either Type Pattern
+
+```dart
+// ✅ Functional error handling
+sealed class Either<L, R> {
+  const Either();
+}
+
+class Left<L, R> extends Either<L, R> {
+  final L value;
+  const Left(this.value);
+}
+
+class Right<L, R> extends Either<L, R> {
+  final R value;
+  const Right(this.value);
+}
+
+// Usage
+Future<Either<AppException, User>> fetchUser(String id) async {
+  try {
+    final user = await _fetchUser(id);
+    return Right(user);
+  } on AppException catch (e) {
+    return Left(e);
+  }
+}
+
+// Pattern matching (Dart 3.0+)
+final result = await fetchUser('123');
+switch (result) {
+  case Left(value: final error):
+    print('Error: ${error.message}');
+  case Right(value: final user):
+    print('User: ${user.name}');
+}
+```
+
+## Validation
+
+```dart
+// ✅ Validate early, throw specific errors
+class UserValidator {
+  static void validate(String email, String password) {
+    if (email.isEmpty) {
+      throw ValidationException('Email is required');
+    }
+
+    if (!email.contains('@')) {
+      throw ValidationException('Invalid email format');
+    }
+
+    if (password.length < 8) {
+      throw ValidationException('Password must be at least 8 characters');
+    }
+  }
+}
+
+// Usage
+try {
+  UserValidator.validate(email, password);
+  await createUser(email, password);
+} on ValidationException catch (e) {
+  showError(e.message);
+}
+```
+
+## Assert for Development
+
+```dart
+// ✅ Use assert for development-time checks
+void transfer(Account from, Account to, double amount) {
+  assert(amount > 0, 'Amount must be positive');
+  assert(from.balance >= amount, 'Insufficient funds');
+
+  from.withdraw(amount);
+  to.deposit(amount);
+}
+
+// Assertions only run in debug mode
+// In production, they're removed
+```
+
+## Error Boundaries (Flutter)
+
+```dart
+// ✅ Catch errors at widget level
+class ErrorBoundary extends StatefulWidget {
+  final Widget child;
+
+  const ErrorBoundary({required this.child});
+
+  @override
+  State<ErrorBoundary> createState() => _ErrorBoundaryState();
+}
+
+class _ErrorBoundaryState extends State<ErrorBoundary> {
+  Object? error;
+
+  @override
+  Widget build(BuildContext context) {
+    if (error != null) {
+      return ErrorWidget(error: error!);
+    }
+
+    return ErrorWrapper(
+      onError: (error, stackTrace) {
+        setState(() => this.error = error);
+      },
+      child: widget.child,
+    );
+  }
+}
+```
+
+## Global Error Handling
+
+```dart
+// ✅ Catch uncaught errors
+void main() {
+  // Synchronous errors
+  FlutterError.onError = (details) {
+    print('Flutter error: ${details.exception}');
+    print('Stack trace: ${details.stack}');
+    reportError(details.exception, details.stack);
+  };
+
+  // Asynchronous errors
+  PlatformDispatcher.instance.onError = (error, stack) {
+    print('Async error: $error');
+    reportError(error, stack);
+    return true;
+  };
+
+  runApp(MyApp());
+}
+
+void reportError(Object error, StackTrace? stackTrace) {
+  // Send to error tracking service
+}
+```
+
+## Retry Pattern
+
+```dart
+// ✅ Retry with exponential backoff
+Future<T> retryWithBackoff<T>(
+  Future<T> Function() operation, {
+  int maxAttempts = 3,
+  Duration initialDelay = const Duration(seconds: 1),
+}) async {
+  int attempt = 0;
+  while (true) {
+    try {
+      return await operation();
+    } catch (e) {
+      attempt++;
+      if (attempt >= maxAttempts) rethrow;
+
+      final delay = initialDelay * (1 << attempt); // Exponential backoff
+      print('Retry attempt $attempt after $delay');
+      await Future.delayed(delay);
+    }
+  }
+}
+
+// Usage
+final user = await retryWithBackoff(
+  () => fetchUser('123'),
+  maxAttempts: 5,
+);
+```
+
+## Circuit Breaker Pattern
+
+```dart
+// ✅ Prevent cascading failures
+class CircuitBreaker {
+  final int failureThreshold;
+  final Duration timeout;
+
+  int _failureCount = 0;
+  DateTime? _openedAt;
+
+  CircuitBreaker({
+    this.failureThreshold = 5,
+    this.timeout = const Duration(minutes: 1),
+  });
+
+  Future<T> execute<T>(Future<T> Function() operation) async {
+    if (_isOpen()) {
+      if (_shouldReset()) {
+        _reset();
+      } else {
+        throw AppException('Circuit breaker is open');
+      }
+    }
+
+    try {
+      final result = await operation();
+      _onSuccess();
+      return result;
+    } catch (e) {
+      _onFailure();
+      rethrow;
+    }
+  }
+
+  bool _isOpen() => _openedAt != null;
+
+  bool _shouldReset() {
+    return _openedAt != null &&
+        DateTime.now().difference(_openedAt!) > timeout;
+  }
+
+  void _onSuccess() {
+    _failureCount = 0;
+  }
+
+  void _onFailure() {
+    _failureCount++;
+    if (_failureCount >= failureThreshold) {
+      _openedAt = DateTime.now();
+    }
+  }
+
+  void _reset() {
+    _failureCount = 0;
+    _openedAt = null;
+  }
+}
+```
+
+## Best Practices
+
+- Create custom exception classes for different error types
+- Catch specific exceptions before general ones
+- Use `rethrow` to preserve stack traces
+- Always clean up resources in `finally` blocks
+- Validate input early and throw meaningful errors
+- Use Result/Either types for expected failures
+- Implement global error handlers for uncaught errors
+- Use retry with exponential backoff for transient failures
+- Implement circuit breakers for external service calls
+- Don't catch exceptions you can't handle
+- Include context in error messages
+- Log errors with stack traces

package/data/language/dart/index.md

@@ -0,0 +1,10 @@
+# Dart Language Guidelines
+
+Comprehensive guidelines for writing idiomatic Dart code.
+
+## Topics
+
+- [Fundamentals](basics.md) - Types, null safety, syntax
+- [Async Programming](async.md) - Futures, async/await, Streams
+- [Error Handling](error-handling.md) - Exceptions and error patterns
+- [Testing](testing.md) - Unit and widget testing

package/data/language/dart/testing.md

@@ -0,0 +1,352 @@
+# Testing in Dart
+
+## Unit Testing
+
+```dart
+import 'package:test/test.dart';
+
+// ✅ Arrange-Act-Assert pattern
+void main() {
+  group('UserService', () {
+    test('should create user with hashed password', () async {
+      // Arrange
+      final repository = MockUserRepository();
+      final service = UserService(repository);
+      final userData = UserData(email: 'test@example.com', password: 'secret');
+
+      // Act
+      final user = await service.createUser(userData);
+
+      // Assert
+      expect(user.email, equals('test@example.com'));
+      expect(user.passwordHash, isNot(equals('secret')));
+      verify(repository.save(any)).called(1);
+    });
+
+    test('should throw ValidationException for invalid email', () {
+      final service = UserService(MockUserRepository());
+
+      expect(
+        () => service.createUser(UserData(email: 'invalid', password: 'pass')),
+        throwsA(isA<ValidationException>()),
+      );
+    });
+  });
+}
+```
+
+## Test Organization
+
+```dart
+void main() {
+  // ✅ Use group for related tests
+  group('Calculator', () {
+    late Calculator calculator;
+
+    // setUp runs before each test
+    setUp(() {
+      calculator = Calculator();
+    });
+
+    // tearDown runs after each test
+    tearDown(() {
+      calculator.dispose();
+    });
+
+    test('adds two numbers', () {
+      expect(calculator.add(2, 3), equals(5));
+    });
+
+    test('subtracts two numbers', () {
+      expect(calculator.subtract(5, 3), equals(2));
+    });
+
+    group('division', () {
+      test('divides two numbers', () {
+        expect(calculator.divide(10, 2), equals(5));
+      });
+
+      test('throws on division by zero', () {
+        expect(
+          () => calculator.divide(10, 0),
+          throwsA(isA<DivisionByZeroException>()),
+        );
+      });
+    });
+  });
+}
+```
+
+## Matchers
+
+```dart
+// Equality
+expect(value, equals(expected));
+expect(value, isNot(equals(unexpected)));
+
+// Types
+expect(value, isA<String>());
+expect(value, isNotNull);
+expect(value, isNull);
+
+// Numbers
+expect(value, greaterThan(5));
+expect(value, lessThan(10));
+expect(value, closeTo(3.14, 0.01));
+
+// Strings
+expect(text, contains('hello'));
+expect(text, startsWith('Hello'));
+expect(text, endsWith('world'));
+expect(text, matches(r'^\d+$'));
+
+// Collections
+expect(list, isEmpty);
+expect(list, isNotEmpty);
+expect(list, hasLength(3));
+expect(list, contains(item));
+expect(map, containsValue(value));
+
+// Futures
+expect(future, completes);
+expect(future, throwsException);
+expect(future, completion(equals(value)));
+
+// Custom matchers
+expect(user, isA<User>().having((u) => u.email, 'email', 'test@example.com'));
+```
+
+## Mocking with Mockito
+
+```dart
+import 'package:mockito/mockito.dart';
+import 'package:mockito/annotations.dart';
+
+// Generate mocks
+@GenerateMocks([UserRepository, ApiClient])
+void main() {
+  group('UserService', () {
+    late MockUserRepository repository;
+    late UserService service;
+
+    setUp(() {
+      repository = MockUserRepository();
+      service = UserService(repository);
+    });
+
+    test('should fetch user by id', () async {
+      // Arrange - stub method
+      final expectedUser = User(id: '1', name: 'Alice');
+      when(repository.findById('1')).thenAnswer((_) async => expectedUser);
+
+      // Act
+      final user = await service.getUser('1');
+
+      // Assert
+      expect(user, equals(expectedUser));
+      verify(repository.findById('1')).called(1);
+    });
+
+    test('should handle not found', () async {
+      // Stub to return null
+      when(repository.findById(any)).thenAnswer((_) async => null);
+
+      expect(
+        () => service.getUser('999'),
+        throwsA(isA<NotFoundException>()),
+      );
+    });
+  });
+}
+```
+
+## Testing Async Code
+
+```dart
+test('should fetch data asynchronously', () async {
+  final data = await fetchData();
+  expect(data, isNotNull);
+});
+
+test('should complete within timeout', () async {
+  await expectLater(
+    slowOperation().timeout(const Duration(seconds: 2)),
+    completes,
+  );
+});
+
+test('should handle errors', () {
+  expect(
+    failingOperation(),
+    throwsA(isA<NetworkException>()),
+  );
+});
+```
+
+## Testing Streams
+
+```dart
+test('should emit values from stream', () async {
+  final stream = Stream.fromIterable([1, 2, 3]);
+
+  expect(stream, emitsInOrder([1, 2, 3]));
+});
+
+test('should emit and complete', () {
+  expect(
+    countStream(3),
+    emitsInOrder([
+      1,
+      2,
+      3,
+      emitsDone,
+    ]),
+  );
+});
+
+test('should handle stream errors', () {
+  expect(
+    errorStream(),
+    emitsInOrder([
+      1,
+      emitsError(isA<Exception>()),
+    ]),
+  );
+});
+```
+
+## Widget Testing (Flutter)
+
+```dart
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('should display user name', (WidgetTester tester) async {
+    // Arrange
+    final user = User(id: '1', name: 'Alice');
+
+    // Act
+    await tester.pumpWidget(
+      MaterialApp(home: UserProfile(user: user)),
+    );
+
+    // Assert
+    expect(find.text('Alice'), findsOneWidget);
+  });
+
+  testWidgets('should handle button tap', (WidgetTester tester) async {
+    bool tapped = false;
+
+    await tester.pumpWidget(
+      MaterialApp(
+        home: Scaffold(
+          body: ElevatedButton(
+            onPressed: () => tapped = true,
+            child: const Text('Tap me'),
+          ),
+        ),
+      ),
+    );
+
+    // Find and tap button
+    await tester.tap(find.text('Tap me'));
+    await tester.pump();
+
+    expect(tapped, isTrue);
+  });
+}
+```
+
+## Integration Testing
+
+```dart
+import 'package:integration_test/integration_test.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  IntegrationTestWidgetsFlutterBinding.ensureInitialized();
+
+  group('Login flow', () {
+    testWidgets('should login successfully', (tester) async {
+      await tester.pumpWidget(MyApp());
+
+      // Enter credentials
+      await tester.enterText(
+        find.byKey(const Key('email_field')),
+        'test@example.com',
+      );
+      await tester.enterText(
+        find.byKey(const Key('password_field')),
+        'password123',
+      );
+
+      // Tap login
+      await tester.tap(find.byKey(const Key('login_button')));
+      await tester.pumpAndSettle();
+
+      // Verify navigation to home
+      expect(find.byType(HomePage), findsOneWidget);
+    });
+  });
+}
+```
+
+## Test Doubles
+
+```dart
+// Fake - working implementation (not for production)
+class FakeUserRepository implements UserRepository {
+  final _users = <String, User>{};
+
+  @override
+  Future<User?> findById(String id) async {
+    return _users[id];
+  }
+
+  @override
+  Future<void> save(User user) async {
+    _users[user.id] = user;
+  }
+}
+
+// Stub - returns canned responses
+class StubApiClient implements ApiClient {
+  @override
+  Future<Response> get(String url) async {
+    return Response(statusCode: 200, data: {'id': '1', 'name': 'Alice'});
+  }
+}
+
+// Mock - pre-programmed with expectations (use Mockito)
+final mock = MockUserRepository();
+when(mock.findById('1')).thenAnswer((_) async => testUser);
+```
+
+## Coverage
+
+```bash
+# Run tests with coverage
+dart test --coverage=coverage
+
+# Generate HTML report
+genhtml coverage/lcov.info -o coverage/html
+
+# View coverage
+open coverage/html/index.html
+```
+
+## Best Practices
+
+- Use `group()` to organize related tests
+- One test per behavior
+- Use descriptive test names: "should [expected behavior] when [scenario]"
+- Follow Arrange-Act-Assert pattern
+- Test observable behavior, not implementation
+- Use setUp/tearDown for common initialization
+- Mock external dependencies
+- Test edge cases and error conditions
+- Keep tests fast and independent
+- Use `pump()` and `pumpAndSettle()` in widget tests
+- Verify interactions with mocks
+- Aim for high code coverage (80%+)
+- Run tests in CI/CD pipeline