@smicolon/ai-kit 0.1.0 → 0.2.0

package/packs/django/rules/serializers.md

@@ -0,0 +1,126 @@
+---
+paths:
+  - "**/serializers.py"
+  - "**/serializers/*.py"
+---
+
+# Django Serializer Standards
+
+## Structure
+
+```python
+import users.models as _users_models
+from rest_framework import serializers
+
+class UserSerializer(serializers.ModelSerializer):
+    """Read serializer for User."""
+
+    class Meta:
+        model = _users_models.User
+        fields = ['id', 'email', 'first_name', 'last_name', 'created_at']
+        read_only_fields = ['id', 'created_at']
+
+
+class CreateUserSerializer(serializers.Serializer):
+    """Write serializer for creating User."""
+
+    email = serializers.EmailField()
+    password = serializers.CharField(write_only=True, min_length=8)
+    first_name = serializers.CharField(max_length=100)
+
+    def validate_email(self, value):
+        if _users_models.User.objects.filter(email=value).exists():
+            raise serializers.ValidationError("Email already exists")
+        return value.lower()
+```
+
+## Import Pattern
+
+```python
+import users.models as _users_models
+from rest_framework import serializers
+```
+
+## Rules
+
+- Separate read/write serializers when needed
+- All validation in serializer, not view
+- Use `validate_<field>` for field-level validation
+- Use `validate` for cross-field validation
+- Never expose sensitive fields (password, tokens)
+
+## Naming Convention
+
+- Read serializers: `{Model}Serializer`
+- Create serializers: `Create{Model}Serializer`
+- Update serializers: `Update{Model}Serializer`
+- List serializers (minimal): `{Model}ListSerializer`
+
+## Validation Examples
+
+### Field-Level Validation
+
+```python
+class CreateUserSerializer(serializers.Serializer):
+    email = serializers.EmailField()
+    password = serializers.CharField(write_only=True)
+
+    def validate_email(self, value):
+        """Normalize and validate email."""
+        value = value.lower().strip()
+        if _users_models.User.objects.filter(email=value).exists():
+            raise serializers.ValidationError("Email already exists")
+        return value
+
+    def validate_password(self, value):
+        """Validate password strength."""
+        if len(value) < 8:
+            raise serializers.ValidationError("Password must be at least 8 characters")
+        if not any(c.isdigit() for c in value):
+            raise serializers.ValidationError("Password must contain a digit")
+        return value
+```
+
+### Cross-Field Validation
+
+```python
+class PasswordChangeSerializer(serializers.Serializer):
+    old_password = serializers.CharField(write_only=True)
+    new_password = serializers.CharField(write_only=True)
+    confirm_password = serializers.CharField(write_only=True)
+
+    def validate(self, data):
+        if data['new_password'] != data['confirm_password']:
+            raise serializers.ValidationError({
+                "confirm_password": "Passwords do not match"
+            })
+        if data['old_password'] == data['new_password']:
+            raise serializers.ValidationError({
+                "new_password": "New password must be different"
+            })
+        return data
+```
+
+## Nested Serializers
+
+```python
+class OrderItemSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = _models.OrderItem
+        fields = ['id', 'product', 'quantity', 'price']
+
+class OrderSerializer(serializers.ModelSerializer):
+    items = OrderItemSerializer(many=True, read_only=True)
+    total = serializers.DecimalField(max_digits=10, decimal_places=2, read_only=True)
+
+    class Meta:
+        model = _models.Order
+        fields = ['id', 'user', 'items', 'total', 'created_at']
+```
+
+## Forbidden Patterns
+
+- Business logic in serializers (use services)
+- Direct database queries (use services)
+- Exposing sensitive fields
+- Using ModelSerializer for write operations with complex logic

package/packs/django/rules/services.md

@@ -0,0 +1,131 @@
+---
+paths:
+  - "**/services.py"
+  - "**/services/*.py"
+---
+
+# Django Service Layer Standards
+
+## Purpose
+
+Services contain business logic. Views delegate to services.
+
+## Structure
+
+```python
+import users.models as _users_models
+from django.db import transaction
+
+class UserService:
+    """
+    Business logic for User operations.
+    All methods are static or class methods.
+    """
+
+    @staticmethod
+    @transaction.atomic
+    def create_user(data: dict) -> _users_models.User:
+        """
+        Create a new user with validation.
+
+        Args:
+            data: Validated user data from serializer
+
+        Returns:
+            Created User instance
+
+        Raises:
+            ValidationError: If email already exists
+        """
+        # Business logic here
+        user = _users_models.User.objects.create(**data)
+        # Side effects (emails, notifications)
+        return user
+```
+
+## Requirements
+
+- All database operations use `@transaction.atomic`
+- Methods have type hints
+- Docstrings explain purpose, args, returns, raises
+- Static methods preferred (no instance state)
+- Import pattern: `import app.models as _models`
+
+## Forbidden Patterns
+
+- Service methods calling views
+- Circular service dependencies
+- HTTP-specific code (request, response)
+- Direct print statements (use logging)
+- Catching broad exceptions without re-raising
+
+## Method Patterns
+
+### Query Methods
+
+```python
+@staticmethod
+def get_by_id(user_id: uuid.UUID) -> _users_models.User:
+    """Get user by ID or raise DoesNotExist."""
+    return _users_models.User.objects.get(id=user_id, is_deleted=False)
+
+@staticmethod
+def get_active_users() -> QuerySet[_users_models.User]:
+    """Get all active users."""
+    return _users_models.User.objects.filter(is_active=True, is_deleted=False)
+```
+
+### Mutation Methods
+
+```python
+@staticmethod
+@transaction.atomic
+def update_user(user_id: uuid.UUID, data: dict) -> _users_models.User:
+    """Update user fields."""
+    user = _users_models.User.objects.select_for_update().get(id=user_id)
+    for key, value in data.items():
+        setattr(user, key, value)
+    user.save()
+    return user
+
+@staticmethod
+@transaction.atomic
+def soft_delete_user(user_id: uuid.UUID) -> None:
+    """Soft delete a user."""
+    _users_models.User.objects.filter(id=user_id).update(is_deleted=True)
+```
+
+## Error Handling
+
+```python
+import logging
+from django.core.exceptions import ValidationError
+
+logger = logging.getLogger(__name__)
+
+class UserService:
+    @staticmethod
+    @transaction.atomic
+    def create_user(data: dict) -> _users_models.User:
+        try:
+            user = _users_models.User.objects.create(**data)
+            logger.info(f"Created user: {user.id}")
+            return user
+        except IntegrityError as e:
+            logger.error(f"Failed to create user: {e}")
+            raise ValidationError("User with this email already exists")
+```
+
+## Testing Services
+
+Services should be the primary unit test target:
+
+```python
+@pytest.mark.django_db
+class TestUserService:
+    def test_create_user_success(self):
+        data = {'email': 'test@example.com', 'password': 'secure123'}
+        user = UserService.create_user(data)
+        assert user.id is not None
+        assert user.email == 'test@example.com'
+```

package/packs/django/rules/tests.md

@@ -0,0 +1,140 @@
+---
+paths:
+  - "**/test*.py"
+  - "**/tests/**/*.py"
+  - "**/*_test.py"
+---
+
+# Django Test Standards
+
+## Coverage Target: 90%+
+
+## Structure
+
+```python
+import pytest
+import users.models as _users_models
+import users.services as _users_services
+from rest_framework.test import APIClient
+from rest_framework import status
+
+@pytest.mark.django_db
+class TestUserService:
+    """Tests for UserService."""
+
+    def test_create_user_success(self):
+        """Test successful user creation."""
+        data = {'email': 'test@example.com', 'password': 'secure123'}
+
+        user = _users_services.UserService.create_user(data)
+
+        assert user.id is not None
+        assert user.email == 'test@example.com'
+        assert user.created_at is not None
+
+    def test_create_user_duplicate_email(self):
+        """Test creation fails with duplicate email."""
+        _users_models.User.objects.create(email='existing@example.com')
+
+        with pytest.raises(ValidationError) as exc:
+            _users_services.UserService.create_user({'email': 'existing@example.com'})
+
+        assert 'email' in str(exc.value)
+```
+
+## Requirements
+
+- Use pytest, not unittest
+- Import pattern: `import app.models as _app_models`
+- Minimum 2 assertions per test
+- Test happy path AND error paths
+- Use factories for complex data (factory_boy)
+- Mark DB tests with `@pytest.mark.django_db`
+
+## Test Categories
+
+1. Unit tests (80%): Models, services, utilities
+2. Integration tests (15%): API endpoints
+3. Edge cases (5%): Boundaries, errors
+
+## Forbidden Patterns
+
+- Tests without assertions
+- `assert True` or `assert obj` (meaningless)
+- Shared mutable state between tests
+- Skipped tests without explanation
+
+## Test Naming
+
+```python
+# Pattern: test_{method}_{scenario}_{expected_result}
+def test_create_user_success(self):
+def test_create_user_duplicate_email_raises_validation_error(self):
+def test_get_user_not_found_raises_does_not_exist(self):
+```
+
+## API Test Pattern
+
+```python
+@pytest.mark.django_db
+class TestUserAPI:
+    """API tests for User endpoints."""
+
+    @pytest.fixture
+    def client(self):
+        return APIClient()
+
+    @pytest.fixture
+    def authenticated_client(self, user):
+        client = APIClient()
+        client.force_authenticate(user=user)
+        return client
+
+    def test_list_users_unauthenticated_returns_401(self, client):
+        response = client.get('/api/users/')
+        assert response.status_code == status.HTTP_401_UNAUTHORIZED
+
+    def test_list_users_authenticated_returns_200(self, authenticated_client):
+        response = authenticated_client.get('/api/users/')
+        assert response.status_code == status.HTTP_200_OK
+        assert 'results' in response.data
+```
+
+## Factory Pattern
+
+```python
+import factory
+from factory.django import DjangoModelFactory
+import users.models as _users_models
+
+class UserFactory(DjangoModelFactory):
+    class Meta:
+        model = _users_models.User
+
+    email = factory.Sequence(lambda n: f'user{n}@example.com')
+    first_name = factory.Faker('first_name')
+    last_name = factory.Faker('last_name')
+    is_active = True
+
+# Usage in tests
+def test_list_users(self, authenticated_client):
+    UserFactory.create_batch(5)
+    response = authenticated_client.get('/api/users/')
+    assert len(response.data['results']) == 5
+```
+
+## Fixtures
+
+```python
+@pytest.fixture
+def user():
+    return UserFactory()
+
+@pytest.fixture
+def admin_user():
+    return UserFactory(is_staff=True, is_superuser=True)
+
+@pytest.fixture
+def product(user):
+    return ProductFactory(owner=user)
+```

package/packs/django/rules/views.md

@@ -0,0 +1,102 @@
+---
+paths:
+  - "**/views.py"
+  - "**/views/*.py"
+  - "**/viewsets.py"
+---
+
+# Django View Standards
+
+## Required Security
+
+EVERY view/viewset MUST have:
+
+```python
+from rest_framework.permissions import IsAuthenticated
+from rest_framework.throttling import UserRateThrottle
+
+class YourViewSet(viewsets.ModelViewSet):
+    # REQUIRED - No exceptions
+    permission_classes = [IsAuthenticated]
+    throttle_classes = [UserRateThrottle]
+```
+
+## Import Pattern
+
+```python
+# CORRECT - Modular imports with aliases
+import users.models as _users_models
+import users.services as _users_services
+import users.serializers as _users_serializers
+
+# Usage
+queryset = _users_users_models.User.objects.filter(is_deleted=False)
+serializer_class = _users_users_serializers.UserSerializer
+```
+
+## View Structure
+
+```python
+class UserViewSet(viewsets.ModelViewSet):
+    permission_classes = [IsAuthenticated]
+    throttle_classes = [UserRateThrottle]
+
+    # Use service layer - no raw ORM in views
+    def create(self, request):
+        serializer = _users_serializers.CreateUserSerializer(data=request.data)
+        serializer.is_valid(raise_exception=True)
+        user = _users_users_services.UserService.create(serializer.validated_data)
+        return Response(_users_users_serializers.UserSerializer(user).data, status=201)
+```
+
+## Forbidden Patterns
+
+- Views without permission_classes
+- Direct `request.data` access without serializer
+- ORM queries in view methods (use services)
+- `@api_view` without `@permission_classes`
+- Hardcoded status codes (use `status.HTTP_*`)
+
+## Response Patterns
+
+```python
+from rest_framework import status
+from rest_framework.response import Response
+
+# CORRECT
+return Response(data, status=status.HTTP_201_CREATED)
+return Response(status=status.HTTP_204_NO_CONTENT)
+
+# WRONG
+return Response(data, status=201)  # Use named constants
+```
+
+## Error Handling
+
+```python
+from rest_framework.exceptions import NotFound, PermissionDenied
+
+class UserViewSet(viewsets.ModelViewSet):
+    def retrieve(self, request, pk=None):
+        try:
+            user = _users_users_services.UserService.get_by_id(pk)
+        except _users_users_models.User.DoesNotExist:
+            raise NotFound("User not found")
+        return Response(_users_users_serializers.UserSerializer(user).data)
+```
+
+## Pagination
+
+Always use pagination for list views:
+
+```python
+from rest_framework.pagination import PageNumberPagination
+
+class StandardPagination(PageNumberPagination):
+    page_size = 20
+    page_size_query_param = 'page_size'
+    max_page_size = 100
+
+class UserViewSet(viewsets.ModelViewSet):
+    pagination_class = StandardPagination
+```