@malamute/ai-rules 1.0.0 → 1.3.0

package/configs/fastapi/rules/routers.md

@@ -0,0 +1,202 @@
+---
+paths:
+  - "**/routers/**/*.py"
+  - "**/routes/**/*.py"
+  - "**/api/**/*.py"
+  - "**/endpoints/**/*.py"
+---
+
+# FastAPI Router Patterns
+
+## Router Organization
+
+```python
+# GOOD - organized router structure
+# app/users/router.py
+from fastapi import APIRouter, status
+
+router = APIRouter(
+    prefix="/users",
+    tags=["Users"],
+    responses={404: {"description": "User not found"}},
+)
+
+@router.get("/", response_model=list[UserResponse])
+async def list_users(db: DbSession) -> list[User]:
+    """List all active users."""
+    return await db.scalars(select(User).where(User.is_active))
+
+@router.post("/", status_code=status.HTTP_201_CREATED)
+async def create_user(data: UserCreate, db: DbSession) -> UserResponse:
+    """Create a new user."""
+    user = User(**data.model_dump())
+    db.add(user)
+    await db.commit()
+    return user
+
+@router.get("/{user_id}")
+async def get_user(user_id: int, db: DbSession) -> UserResponse:
+    """Get user by ID."""
+    user = await db.get(User, user_id)
+    if not user:
+        raise HTTPException(404, "User not found")
+    return user
+```
+
+## Router Registration
+
+```python
+# app/main.py
+from fastapi import FastAPI
+from app.users.router import router as users_router
+from app.auth.router import router as auth_router
+from app.products.router import router as products_router
+
+app = FastAPI(title="My API", version="1.0.0")
+
+# Version prefix
+api_v1 = APIRouter(prefix="/api/v1")
+api_v1.include_router(users_router)
+api_v1.include_router(auth_router)
+api_v1.include_router(products_router)
+
+app.include_router(api_v1)
+```
+
+## Path Parameters
+
+```python
+# GOOD - typed path parameters with validation
+@router.get("/{user_id}")
+async def get_user(
+    user_id: Annotated[int, Path(ge=1, description="User ID")],
+) -> UserResponse:
+    ...
+
+# UUID path parameter
+@router.get("/{item_id}")
+async def get_item(item_id: UUID) -> ItemResponse:
+    ...
+
+# Multiple path parameters
+@router.get("/{user_id}/orders/{order_id}")
+async def get_user_order(user_id: int, order_id: int) -> OrderResponse:
+    ...
+```
+
+## Query Parameters
+
+```python
+# GOOD - query parameters with defaults and validation
+@router.get("/")
+async def list_items(
+    skip: int = Query(0, ge=0),
+    limit: int = Query(20, ge=1, le=100),
+    search: str | None = Query(None, min_length=1, max_length=100),
+    status: ItemStatus | None = None,
+    sort_by: Literal["name", "created_at", "price"] = "created_at",
+    order: Literal["asc", "desc"] = "desc",
+) -> Page[ItemResponse]:
+    ...
+
+# List query parameter
+@router.get("/")
+async def get_items(
+    ids: Annotated[list[int], Query()] = [],
+) -> list[ItemResponse]:
+    ...
+```
+
+## Request Body
+
+```python
+# GOOD - explicit body parameter
+@router.post("/")
+async def create_item(
+    item: Annotated[ItemCreate, Body(embed=True)],
+) -> ItemResponse:
+    ...
+
+# Multiple body parameters
+@router.post("/transfer")
+async def transfer(
+    source: Annotated[Account, Body()],
+    destination: Annotated[Account, Body()],
+    amount: Annotated[Decimal, Body(gt=0)],
+) -> TransferResult:
+    ...
+```
+
+## Response Configuration
+
+```python
+# GOOD - explicit response models and status codes
+@router.post(
+    "/",
+    response_model=UserResponse,
+    status_code=status.HTTP_201_CREATED,
+    responses={
+        201: {"description": "User created successfully"},
+        400: {"model": ErrorResponse, "description": "Validation error"},
+        409: {"model": ErrorResponse, "description": "Email already exists"},
+    },
+)
+async def create_user(data: UserCreate) -> User:
+    ...
+
+# Exclude fields from response
+@router.get("/", response_model_exclude={"password", "secret"})
+async def get_user() -> User:
+    ...
+
+# Dynamic response model
+@router.get("/", response_model=UserResponse | AdminResponse)
+async def get_current(user: CurrentUser) -> User:
+    return user
+```
+
+## File Uploads
+
+```python
+from fastapi import File, UploadFile
+
+@router.post("/upload")
+async def upload_file(
+    file: Annotated[UploadFile, File(description="File to upload")],
+) -> dict:
+    contents = await file.read()
+    return {"filename": file.filename, "size": len(contents)}
+
+# Multiple files
+@router.post("/upload-many")
+async def upload_files(
+    files: Annotated[list[UploadFile], File()],
+) -> list[dict]:
+    return [{"filename": f.filename} for f in files]
+```
+
+## Form Data
+
+```python
+from fastapi import Form
+
+@router.post("/login")
+async def login(
+    username: Annotated[str, Form()],
+    password: Annotated[str, Form()],
+) -> Token:
+    ...
+```
+
+## Headers and Cookies
+
+```python
+from fastapi import Header, Cookie
+
+@router.get("/")
+async def get_items(
+    x_token: Annotated[str, Header()],
+    session_id: Annotated[str | None, Cookie()] = None,
+) -> list[Item]:
+    ...
+```

package/configs/fastapi/rules/security.md

@@ -0,0 +1,222 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# FastAPI Security Patterns
+
+## OAuth2 Password Flow
+
+```python
+from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/auth/token")
+
+@router.post("/token")
+async def login(
+    form_data: Annotated[OAuth2PasswordRequestForm, Depends()],
+    db: DbSession,
+) -> Token:
+    user = await authenticate_user(db, form_data.username, form_data.password)
+    if not user:
+        raise HTTPException(
+            status_code=401,
+            detail="Incorrect username or password",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    access_token = create_access_token(data={"sub": str(user.id)})
+    return Token(access_token=access_token, token_type="bearer")
+```
+
+## JWT Authentication
+
+```python
+from jose import JWTError, jwt
+from datetime import datetime, timedelta
+
+SECRET_KEY = settings.secret_key
+ALGORITHM = "HS256"
+ACCESS_TOKEN_EXPIRE_MINUTES = 30
+
+def create_access_token(data: dict) -> str:
+    to_encode = data.copy()
+    expire = datetime.utcnow() + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
+    to_encode.update({"exp": expire})
+    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
+
+async def get_current_user(
+    token: Annotated[str, Depends(oauth2_scheme)],
+    db: DbSession,
+) -> User:
+    credentials_exception = HTTPException(
+        status_code=401,
+        detail="Could not validate credentials",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+
+    try:
+        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
+        user_id: str = payload.get("sub")
+        if user_id is None:
+            raise credentials_exception
+    except JWTError:
+        raise credentials_exception
+
+    user = await db.get(User, int(user_id))
+    if user is None:
+        raise credentials_exception
+
+    return user
+
+CurrentUser = Annotated[User, Depends(get_current_user)]
+```
+
+## API Key Authentication
+
+```python
+from fastapi.security import APIKeyHeader, APIKeyQuery
+
+api_key_header = APIKeyHeader(name="X-API-Key", auto_error=False)
+api_key_query = APIKeyQuery(name="api_key", auto_error=False)
+
+async def get_api_key(
+    api_key_header: str | None = Depends(api_key_header),
+    api_key_query: str | None = Depends(api_key_query),
+) -> str:
+    api_key = api_key_header or api_key_query
+    if not api_key:
+        raise HTTPException(403, "API key required")
+
+    if not await verify_api_key(api_key):
+        raise HTTPException(403, "Invalid API key")
+
+    return api_key
+
+@router.get("/data", dependencies=[Depends(get_api_key)])
+async def get_data() -> dict:
+    ...
+```
+
+## Role-Based Access Control
+
+```python
+from enum import Enum
+from functools import wraps
+
+class Role(str, Enum):
+    USER = "user"
+    ADMIN = "admin"
+    MODERATOR = "moderator"
+
+def require_roles(*roles: Role):
+    async def dependency(user: CurrentUser) -> User:
+        if user.role not in roles:
+            raise HTTPException(
+                status_code=403,
+                detail=f"Required roles: {', '.join(r.value for r in roles)}",
+            )
+        return user
+    return dependency
+
+AdminOnly = Annotated[User, Depends(require_roles(Role.ADMIN))]
+ModeratorOrAdmin = Annotated[User, Depends(require_roles(Role.ADMIN, Role.MODERATOR))]
+
+@router.delete("/{user_id}")
+async def delete_user(user_id: int, admin: AdminOnly) -> None:
+    ...
+```
+
+## Permission-Based Access
+
+```python
+class Permission(str, Enum):
+    READ_USERS = "read:users"
+    WRITE_USERS = "write:users"
+    DELETE_USERS = "delete:users"
+
+def require_permissions(*permissions: Permission):
+    async def dependency(user: CurrentUser) -> User:
+        user_permissions = set(user.permissions)
+        required = set(permissions)
+
+        if not required.issubset(user_permissions):
+            missing = required - user_permissions
+            raise HTTPException(
+                status_code=403,
+                detail=f"Missing permissions: {', '.join(p.value for p in missing)}",
+            )
+        return user
+    return dependency
+
+CanDeleteUsers = Annotated[User, Depends(require_permissions(Permission.DELETE_USERS))]
+```
+
+## Password Hashing
+
+```python
+from passlib.context import CryptContext
+
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+def hash_password(password: str) -> str:
+    return pwd_context.hash(password)
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    return pwd_context.verify(plain_password, hashed_password)
+
+async def authenticate_user(db: DbSession, email: str, password: str) -> User | None:
+    user = await db.scalar(select(User).where(User.email == email))
+    if not user:
+        return None
+    if not verify_password(password, user.hashed_password):
+        return None
+    return user
+```
+
+## CORS Configuration
+
+```python
+from fastapi.middleware.cors import CORSMiddleware
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins,  # ["https://example.com"]
+    allow_credentials=True,
+    allow_methods=["GET", "POST", "PUT", "DELETE"],
+    allow_headers=["*"],
+    expose_headers=["X-Request-ID"],
+)
+```
+
+## Security Headers Middleware
+
+```python
+from starlette.middleware.base import BaseHTTPMiddleware
+
+class SecurityHeadersMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next):
+        response = await call_next(request)
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["X-Frame-Options"] = "DENY"
+        response.headers["X-XSS-Protection"] = "1; mode=block"
+        response.headers["Strict-Transport-Security"] = "max-age=31536000; includeSubDomains"
+        return response
+
+app.add_middleware(SecurityHeadersMiddleware)
+```
+
+## Rate Limiting
+
+```python
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+
+limiter = Limiter(key_func=get_remote_address)
+app.state.limiter = limiter
+
+@router.get("/")
+@limiter.limit("10/minute")
+async def get_items(request: Request) -> list[Item]:
+    ...
+```

package/configs/fastapi/rules/testing.md

@@ -0,0 +1,251 @@
+---
+paths:
+  - "tests/**/*.py"
+  - "**/test_*.py"
+---
+
+# FastAPI Testing Patterns
+
+## Test Client Setup
+
+```python
+import pytest
+from httpx import AsyncClient, ASGITransport
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+from sqlalchemy.orm import sessionmaker
+
+from app.main import app
+from app.database import Base, get_db
+
+TEST_DATABASE_URL = "sqlite+aiosqlite:///./test.db"
+
+@pytest.fixture(scope="session")
+def event_loop():
+    import asyncio
+    loop = asyncio.new_event_loop()
+    yield loop
+    loop.close()
+
+@pytest.fixture(scope="session")
+async def engine():
+    engine = create_async_engine(TEST_DATABASE_URL)
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    yield engine
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.drop_all)
+    await engine.dispose()
+
+@pytest.fixture
+async def db_session(engine):
+    async_session = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
+    async with async_session() as session:
+        yield session
+        await session.rollback()
+
+@pytest.fixture
+async def client(db_session):
+    async def override_get_db():
+        yield db_session
+
+    app.dependency_overrides[get_db] = override_get_db
+
+    async with AsyncClient(
+        transport=ASGITransport(app=app),
+        base_url="http://test",
+    ) as client:
+        yield client
+
+    app.dependency_overrides.clear()
+```
+
+## API Tests
+
+```python
+class TestUsersAPI:
+    async def test_create_user(self, client: AsyncClient):
+        response = await client.post("/api/v1/users", json={
+            "email": "test@example.com",
+            "password": "password123",
+            "name": "Test User",
+        })
+
+        assert response.status_code == 201
+        data = response.json()
+        assert data["email"] == "test@example.com"
+        assert "id" in data
+        assert "password" not in data
+
+    async def test_create_user_duplicate_email(self, client: AsyncClient, db_session):
+        # Create existing user
+        user = User(email="existing@example.com", name="Existing")
+        db_session.add(user)
+        await db_session.commit()
+
+        response = await client.post("/api/v1/users", json={
+            "email": "existing@example.com",
+            "password": "password123",
+            "name": "New User",
+        })
+
+        assert response.status_code == 409
+        assert "already exists" in response.json()["detail"]
+
+    async def test_get_user_not_found(self, client: AsyncClient):
+        response = await client.get("/api/v1/users/99999")
+
+        assert response.status_code == 404
+
+    async def test_list_users_pagination(self, client: AsyncClient, db_session):
+        # Create users
+        for i in range(25):
+            db_session.add(User(email=f"user{i}@example.com", name=f"User {i}"))
+        await db_session.commit()
+
+        response = await client.get("/api/v1/users?page=2&size=10")
+
+        assert response.status_code == 200
+        data = response.json()
+        assert len(data["items"]) == 10
+        assert data["total"] == 25
+        assert data["page"] == 2
+```
+
+## Authentication Tests
+
+```python
+@pytest.fixture
+async def auth_headers(client: AsyncClient, db_session):
+    # Create user
+    user = User(email="auth@example.com", name="Auth User")
+    user.set_password("password123")
+    db_session.add(user)
+    await db_session.commit()
+
+    # Get token
+    response = await client.post("/api/v1/auth/login", data={
+        "username": "auth@example.com",
+        "password": "password123",
+    })
+    token = response.json()["access_token"]
+
+    return {"Authorization": f"Bearer {token}"}
+
+class TestAuthenticatedEndpoints:
+    async def test_get_me_unauthorized(self, client: AsyncClient):
+        response = await client.get("/api/v1/users/me")
+        assert response.status_code == 401
+
+    async def test_get_me_authorized(self, client: AsyncClient, auth_headers):
+        response = await client.get("/api/v1/users/me", headers=auth_headers)
+        assert response.status_code == 200
+        assert response.json()["email"] == "auth@example.com"
+```
+
+## Dependency Override
+
+```python
+from unittest.mock import AsyncMock
+
+@pytest.fixture
+def mock_email_service():
+    return AsyncMock()
+
+async def test_signup_sends_email(client: AsyncClient, mock_email_service):
+    app.dependency_overrides[get_email_service] = lambda: mock_email_service
+
+    response = await client.post("/api/v1/auth/signup", json={
+        "email": "new@example.com",
+        "password": "password123",
+        "name": "New User",
+    })
+
+    assert response.status_code == 201
+    mock_email_service.send_welcome.assert_called_once_with("new@example.com")
+
+    app.dependency_overrides.clear()
+```
+
+## WebSocket Tests
+
+```python
+from httpx_ws import aconnect_ws
+
+async def test_websocket_echo(client: AsyncClient):
+    async with aconnect_ws("http://test/ws", client) as ws:
+        await ws.send_text("Hello")
+        response = await ws.receive_text()
+        assert response == "Echo: Hello"
+
+async def test_websocket_auth_required():
+    async with AsyncClient(
+        transport=ASGITransport(app=app),
+        base_url="http://test",
+    ) as client:
+        with pytest.raises(Exception):
+            async with aconnect_ws("http://test/ws", client) as ws:
+                pass  # Should fail without token
+```
+
+## File Upload Tests
+
+```python
+async def test_file_upload(client: AsyncClient, auth_headers):
+    files = {"file": ("test.txt", b"file content", "text/plain")}
+
+    response = await client.post(
+        "/api/v1/files/upload",
+        files=files,
+        headers=auth_headers,
+    )
+
+    assert response.status_code == 201
+    assert response.json()["filename"] == "test.txt"
+```
+
+## Parametrized Tests
+
+```python
+@pytest.mark.parametrize("email,expected_valid", [
+    ("valid@example.com", True),
+    ("also.valid@example.co.uk", True),
+    ("invalid", False),
+    ("missing@", False),
+    ("@nodomain.com", False),
+])
+async def test_email_validation(client: AsyncClient, email: str, expected_valid: bool):
+    response = await client.post("/api/v1/users", json={
+        "email": email,
+        "password": "password123",
+        "name": "Test",
+    })
+
+    if expected_valid:
+        assert response.status_code in (201, 409)  # Created or duplicate
+    else:
+        assert response.status_code == 422
+```
+
+## Test Markers
+
+```python
+# pyproject.toml
+[tool.pytest.ini_options]
+markers = [
+    "slow: marks tests as slow",
+    "integration: requires database",
+]
+
+# Usage
+@pytest.mark.slow
+async def test_heavy_computation():
+    ...
+
+@pytest.mark.integration
+async def test_database_query():
+    ...
+
+# Run specific markers
+# pytest -m "not slow"
+# pytest -m integration
+```