@hivehub/rulebook 1.2.0

package/templates/languages/DART.md

@@ -0,0 +1,332 @@
+<!-- DART:START -->
+# Dart Project Rules
+
+## Agent Automation Commands
+
+**CRITICAL**: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).
+
+```bash
+# Complete quality check sequence:
+dart format --set-exit-if-changed .  # Format check
+dart analyze --fatal-infos  # Linting + analysis
+dart test                   # All tests (100% pass)
+dart test --coverage=coverage  # Coverage check
+
+# Security audit:
+dart pub outdated           # Check outdated deps
+```
+
+## Dart Configuration
+
+**CRITICAL**: Use Dart 3.0+ with sound null safety and strict analysis.
+
+- **Version**: Dart 3.0+
+- **Recommended**: Dart 3.3+
+- **Null Safety**: Sound null safety required
+- **Analysis**: dart analyze with strict mode
+- **Testing**: package:test
+
+### pubspec.yaml Requirements
+
+```yaml
+name: your_package
+description: A comprehensive package description
+version: 0.1.0
+homepage: https://github.com/you/your_package
+
+environment:
+  sdk: '>=3.0.0 <4.0.0'
+
+dependencies:
+  http: ^1.1.0
+  
+dev_dependencies:
+  test: ^1.24.0
+  lints: ^3.0.0
+  coverage: ^1.7.0
+  dart_code_metrics: ^5.7.0
+```
+
+### analysis_options.yaml Requirements
+
+```yaml
+include: package:lints/recommended.yaml
+
+analyzer:
+  language:
+    strict-casts: true
+    strict-inference: true
+    strict-raw-types: true
+  
+  errors:
+    invalid_annotation_target: error
+    missing_required_param: error
+    missing_return: error
+  
+  exclude:
+    - build/**
+    - .dart_tool/**
+
+linter:
+  rules:
+    - always_declare_return_types
+    - always_require_non_null_named_parameters
+    - avoid_print
+    - avoid_relative_lib_imports
+    - avoid_returning_null_for_void
+    - avoid_slow_async_io
+    - avoid_types_as_parameter_names
+    - cancel_subscriptions
+    - close_sinks
+    - prefer_const_constructors
+    - prefer_final_fields
+    - prefer_final_locals
+    - sort_constructors_first
+    - unawaited_futures
+```
+
+## Code Quality Standards
+
+### Mandatory Quality Checks
+
+**CRITICAL**: After implementing ANY feature, you MUST run these commands in order.
+
+**IMPORTANT**: These commands MUST match your GitHub Actions workflows to prevent CI/CD failures!
+
+```bash
+# Pre-Commit Checklist (MUST match .github/workflows/*.yml)
+
+# 1. Format check (matches workflow - use --set-exit-if-changed!)
+dart format --set-exit-if-changed --line-length 100 .
+
+# 2. Analyze (MUST pass with no issues - matches workflow)
+dart analyze --fatal-infos --fatal-warnings
+
+# 3. Run all tests (MUST pass 100% - matches workflow)
+dart test
+
+# 4. Check coverage (MUST meet threshold - matches workflow)
+dart test --coverage=coverage
+dart pub global activate coverage
+dart pub global run coverage:format_coverage \
+  --lcov --in=coverage --out=coverage/lcov.info --report-on=lib
+
+# 5. Metrics check (matches workflow)
+dart pub global activate dart_code_metrics
+dart pub global run dart_code_metrics:metrics analyze lib
+
+# If ANY fails: ❌ DO NOT COMMIT - Fix first!
+```
+
+**If ANY of these fail, you MUST fix the issues before committing.**
+
+**Why This Matters:**
+- Running different commands locally than in CI causes "works on my machine" failures  
+- CI/CD workflows will fail if commands don't match
+- Example: Using `dart format .` locally but `dart format --set-exit-if-changed` in CI = failure
+- Example: Missing `--fatal-infos` flag = warnings pass locally but fail in CI
+
+### Testing
+
+- **Framework**: package:test
+- **Location**: `/test` directory
+- **Coverage**: package:coverage (80%+ threshold)
+- **Naming**: test files must end with `_test.dart`
+
+Example test structure:
+```dart
+import 'package:test/test.dart';
+import 'package:your_package/your_package.dart';
+
+void main() {
+  group('DataProcessor', () {
+    late DataProcessor processor;
+    
+    setUp(() {
+      processor = DataProcessor(threshold: 0.5);
+    });
+    
+    tearDown(() {
+      // Cleanup
+    });
+    
+    test('processes valid input correctly', () {
+      final input = [1, 2, 3, 4, 5];
+      final result = processor.process(input);
+      
+      expect(result, isNotEmpty);
+      expect(result.length, greaterThan(0));
+    });
+    
+    test('handles empty input', () {
+      final result = processor.process([]);
+      expect(result, isEmpty);
+    });
+    
+    test('throws on null input', () {
+      expect(
+        () => processor.process(null as List<int>),
+        throwsA(isA<ArgumentError>()),
+      );
+    });
+  });
+  
+  group('Validator', () {
+    test('validates correct data', () {
+      expect(Validator.isValid('test'), isTrue);
+    });
+    
+    test('rejects invalid data', () {
+      expect(Validator.isValid(''), isFalse);
+    });
+  });
+}
+```
+
+## Null Safety
+
+- **REQUIRED**: Sound null safety for all code
+- Use `?` for nullable types
+- Use `!` operator sparingly
+- Prefer null-aware operators
+
+Example:
+```dart
+// ✅ GOOD: Proper null safety
+class User {
+  final String id;
+  final String name;
+  final String? email;  // Nullable
+  final int? age;       // Nullable
+  
+  User({
+    required this.id,
+    required this.name,
+    this.email,
+    this.age,
+  });
+  
+  String getDisplayName() {
+    return email != null ? '$name <$email>' : name;
+  }
+  
+  int getAgeOrDefault() => age ?? 0;
+}
+
+// ❌ BAD: Unsafe null handling
+class User {
+  String id;
+  String name;
+  String email;  // Should be nullable but isn't
+  
+  User(this.id, this.name, this.email);
+  
+  String getDisplayName() {
+    return '$name <$email>';  // Crash if email is null!
+  }
+}
+```
+
+## Async Programming
+
+- Always use `async`/`await`
+- Handle Future errors with try/catch
+- Use `unawaited()` to mark intentionally unawaited futures
+
+Example:
+```dart
+// ✅ GOOD: Proper async handling
+Future<List<User>> fetchUsers() async {
+  try {
+    final response = await http.get(Uri.parse('https://api.example.com/users'));
+    
+    if (response.statusCode != 200) {
+      throw HttpException('Failed to load users: ${response.statusCode}');
+    }
+    
+    final List<dynamic> data = jsonDecode(response.body);
+    return data.map((json) => User.fromJson(json)).toList();
+  } catch (e) {
+    print('Error fetching users: $e');
+    rethrow;
+  }
+}
+
+// ❌ BAD: No error handling
+Future<List<User>> fetchUsers() async {
+  final response = await http.get(Uri.parse('https://api.example.com/users'));
+  final List<dynamic> data = jsonDecode(response.body);  // Could crash!
+  return data.map((json) => User.fromJson(json)).toList();
+}
+```
+
+## Best Practices
+
+### DO's ✅
+
+- **USE** sound null safety
+- **USE** const constructors when possible
+- **PREFER** final for variables
+- **DOCUMENT** public APIs
+- **HANDLE** errors explicitly
+- **TEST** all code paths
+- **USE** meaningful names
+- **FOLLOW** dart_style guidelines
+
+### DON'Ts ❌
+
+- **NEVER** use `dynamic` unless absolutely necessary
+- **NEVER** suppress analyzer warnings without justification
+- **NEVER** use `print()` in production code (use logging)
+- **NEVER** ignore lint warnings
+- **NEVER** use deprecated APIs
+- **NEVER** commit with failing tests
+- **NEVER** use `!` operator without null check
+
+## CI/CD Requirements
+
+Must include GitHub Actions workflows:
+
+1. **Testing** (`dart-test.yml`):
+   - Test on ubuntu-latest, windows-latest, macos-latest
+   - Dart versions: stable, beta
+   - Upload coverage
+
+2. **Linting** (`dart-lint.yml`):
+   - dart format --set-exit-if-changed
+   - dart analyze --fatal-infos --fatal-warnings
+
+3. **Build** (`dart-build.yml`):
+   - dart compile exe (for CLI apps)
+   - Verify output artifacts
+
+## Publishing to pub.dev
+
+### Prerequisites
+
+1. Create account at https://pub.dev
+2. Run `dart pub login`
+3. Verify package name available
+
+### Publishing Workflow
+
+```bash
+# 1. Update version in pubspec.yaml
+# 2. Update CHANGELOG.md
+# 3. Run all quality checks
+dart format --set-exit-if-changed .
+dart analyze --fatal-infos --fatal-warnings
+dart test
+
+# 4. Dry run
+dart pub publish --dry-run
+
+# 5. Publish
+dart pub publish
+
+# 6. Create git tag
+git tag -a v1.0.0 -m "Release 1.0.0"
+```
+
+<!-- DART:END -->
+