@malamute/ai-rules 1.0.0 → 1.3.0

package/configs/_shared/rules/domain/backend/api-design.md

@@ -0,0 +1,203 @@
+---
+paths:
+  - "**/controllers/**"
+  - "**/routes/**"
+  - "**/routers/**"
+  - "**/endpoints/**"
+  - "**/*.controller.ts"
+  - "**/*_router.py"
+---
+
+# API Design Principles
+
+## REST Conventions
+
+### HTTP Methods
+
+| Method | Usage | Idempotent | Response |
+|--------|-------|------------|----------|
+| `GET` | Read resource(s) | Yes | 200 + data |
+| `POST` | Create resource | No | 201 + created resource |
+| `PUT` | Full update | Yes | 200 + updated resource |
+| `PATCH` | Partial update | Yes | 200 + updated resource |
+| `DELETE` | Remove resource | Yes | 204 No Content |
+
+### URL Structure
+
+```
+GET    /api/v1/users          # List users
+GET    /api/v1/users/:id      # Get single user
+POST   /api/v1/users          # Create user
+PUT    /api/v1/users/:id      # Replace user
+PATCH  /api/v1/users/:id      # Update user fields
+DELETE /api/v1/users/:id      # Delete user
+
+# Nested resources (max 2 levels)
+GET    /api/v1/users/:id/orders
+POST   /api/v1/users/:id/orders
+
+# Actions (when CRUD doesn't fit)
+POST   /api/v1/users/:id/activate
+POST   /api/v1/orders/:id/cancel
+```
+
+### Naming Rules
+
+- Use **plural nouns**: `/users`, `/orders`, `/products`
+- Use **kebab-case**: `/user-profiles`, `/order-items`
+- Avoid verbs in URLs (use HTTP methods instead)
+- Use query params for filtering: `/users?status=active&role=admin`
+
+## Response Format
+
+### Success Response
+
+```json
+{
+  "data": { ... },
+  "meta": {
+    "timestamp": "2024-01-15T10:30:00Z",
+    "requestId": "abc-123"
+  }
+}
+```
+
+### List Response with Pagination
+
+```json
+{
+  "data": [ ... ],
+  "meta": {
+    "total": 100,
+    "page": 1,
+    "pageSize": 20,
+    "totalPages": 5,
+    "hasNext": true,
+    "hasPrevious": false
+  }
+}
+```
+
+### Error Response (RFC 7807 Problem Details)
+
+```json
+{
+  "type": "https://api.example.com/errors/validation",
+  "title": "Validation Error",
+  "status": 400,
+  "detail": "One or more fields failed validation",
+  "instance": "/api/v1/users",
+  "errors": [
+    { "field": "email", "message": "Invalid email format" },
+    { "field": "age", "message": "Must be at least 18" }
+  ],
+  "traceId": "abc-123"
+}
+```
+
+## Status Codes
+
+| Code | When to Use |
+|------|-------------|
+| `200` | Successful GET, PUT, PATCH |
+| `201` | Successful POST (resource created) |
+| `204` | Successful DELETE (no content) |
+| `400` | Bad request (validation error) |
+| `401` | Unauthorized (not authenticated) |
+| `403` | Forbidden (authenticated but not allowed) |
+| `404` | Resource not found |
+| `409` | Conflict (duplicate resource) |
+| `422` | Unprocessable entity (business rule violation) |
+| `429` | Too many requests (rate limited) |
+| `500` | Internal server error |
+
+## Pagination
+
+### Offset-based (simple, for small datasets)
+
+```
+GET /api/v1/users?page=2&pageSize=20
+```
+
+### Cursor-based (performant, for large datasets)
+
+```
+GET /api/v1/users?cursor=eyJpZCI6MTAwfQ&limit=20
+```
+
+Response includes next cursor:
+```json
+{
+  "data": [...],
+  "meta": {
+    "nextCursor": "eyJpZCI6MTIwfQ",
+    "hasMore": true
+  }
+}
+```
+
+## Filtering & Sorting
+
+```
+# Filtering
+GET /api/v1/users?status=active&role=admin
+GET /api/v1/orders?createdAt[gte]=2024-01-01&createdAt[lte]=2024-12-31
+
+# Sorting
+GET /api/v1/users?sort=createdAt:desc
+GET /api/v1/users?sort=lastName:asc,firstName:asc
+
+# Field selection (sparse fieldsets)
+GET /api/v1/users?fields=id,name,email
+```
+
+## Versioning
+
+### URL Path (recommended)
+
+```
+/api/v1/users
+/api/v2/users
+```
+
+### Header-based (alternative)
+
+```
+Accept: application/vnd.api+json; version=1
+```
+
+## Rate Limiting
+
+Include headers in response:
+
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 95
+X-RateLimit-Reset: 1640000000
+Retry-After: 60  (when 429)
+```
+
+## HATEOAS (optional, for discoverability)
+
+```json
+{
+  "data": {
+    "id": "123",
+    "name": "John"
+  },
+  "links": {
+    "self": "/api/v1/users/123",
+    "orders": "/api/v1/users/123/orders",
+    "profile": "/api/v1/users/123/profile"
+  }
+}
+```
+
+## Anti-patterns
+
+- Verbs in URLs: `/api/getUsers` → `/api/users`
+- Singular nouns: `/api/user/123` → `/api/users/123`
+- Deeply nested: `/api/users/1/orders/2/items/3` → `/api/order-items/3`
+- Inconsistent casing: `/api/userProfiles` → `/api/user-profiles`
+- Returning 200 for errors
+- Exposing internal IDs or sensitive data

package/configs/_shared/rules/lang/csharp/async.md

@@ -0,0 +1,220 @@
+---
+paths:
+  - "**/*.cs"
+---
+
+# C# Async Patterns
+
+## Task vs ValueTask
+
+```csharp
+// Use Task for most async operations
+public async Task<User> GetUserAsync(int id)
+
+// Use ValueTask when:
+// 1. Method often completes synchronously
+// 2. Hot path with many allocations
+public async ValueTask<User?> GetCachedUserAsync(int id)
+{
+    if (_cache.TryGetValue(id, out var user))
+        return user;  // Synchronous path - no allocation
+
+    return await _repository.GetByIdAsync(id);
+}
+
+// BAD - ValueTask misuse (awaiting multiple times)
+var task = GetValueTaskAsync();
+await task;
+await task;  // Undefined behavior!
+```
+
+## Parallel Execution
+
+```csharp
+// GOOD - parallel independent operations
+var userTask = _userService.GetUserAsync(userId);
+var ordersTask = _orderService.GetOrdersAsync(userId);
+var prefsTask = _prefService.GetPreferencesAsync(userId);
+
+await Task.WhenAll(userTask, ordersTask, prefsTask);
+
+var user = await userTask;
+var orders = await ordersTask;
+var prefs = await prefsTask;
+
+// BAD - sequential when parallel is possible
+var user = await _userService.GetUserAsync(userId);
+var orders = await _orderService.GetOrdersAsync(userId);
+var prefs = await _prefService.GetPreferencesAsync(userId);
+```
+
+## Task.WhenAll Error Handling
+
+```csharp
+// Handle all exceptions from parallel tasks
+try
+{
+    await Task.WhenAll(task1, task2, task3);
+}
+catch (Exception)
+{
+    // Only first exception is thrown
+    // Check individual tasks for all errors
+    var exceptions = new[] { task1, task2, task3 }
+        .Where(t => t.IsFaulted)
+        .SelectMany(t => t.Exception!.InnerExceptions);
+
+    foreach (var ex in exceptions)
+    {
+        _logger.LogError(ex, "Task failed");
+    }
+    throw;
+}
+```
+
+## Cancellation
+
+```csharp
+// GOOD - check cancellation in loops
+public async Task ProcessBatchAsync(
+    IEnumerable<Item> items,
+    CancellationToken cancellationToken)
+{
+    foreach (var item in items)
+    {
+        cancellationToken.ThrowIfCancellationRequested();
+        await ProcessItemAsync(item, cancellationToken);
+    }
+}
+
+// GOOD - cancellation with timeout
+using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
+try
+{
+    await LongOperationAsync(cts.Token);
+}
+catch (OperationCanceledException)
+{
+    _logger.LogWarning("Operation timed out");
+}
+
+// Link multiple cancellation tokens
+using var linkedCts = CancellationTokenSource.CreateLinkedTokenSource(
+    requestToken,
+    applicationStoppingToken);
+```
+
+## Async Streams
+
+```csharp
+// GOOD - IAsyncEnumerable for streaming data
+public async IAsyncEnumerable<User> GetUsersStreamAsync(
+    [EnumeratorCancellation] CancellationToken cancellationToken = default)
+{
+    await foreach (var user in _context.Users.AsAsyncEnumerable()
+        .WithCancellation(cancellationToken))
+    {
+        yield return user;
+    }
+}
+
+// Consuming async stream
+await foreach (var user in GetUsersStreamAsync(cancellationToken))
+{
+    await ProcessUserAsync(user);
+}
+```
+
+## Avoid Async Pitfalls
+
+```csharp
+// BAD - async void (except event handlers)
+public async void ProcessAsync()  // Exceptions lost, can't await
+{
+    await Task.Delay(1000);
+}
+
+// GOOD - return Task
+public async Task ProcessAsync()
+{
+    await Task.Delay(1000);
+}
+
+// BAD - blocking on async (.Result, .Wait())
+public void Process()
+{
+    var result = GetDataAsync().Result;  // Deadlock risk!
+}
+
+// BAD - unnecessary async/await
+public async Task<int> GetCountAsync()
+{
+    return await _repository.CountAsync();  // Just return the task
+}
+
+// GOOD - return task directly when no additional await needed
+public Task<int> GetCountAsync()
+{
+    return _repository.CountAsync();
+}
+```
+
+## Thread Safety
+
+```csharp
+// GOOD - use concurrent collections
+private readonly ConcurrentDictionary<int, User> _cache = new();
+
+// GOOD - SemaphoreSlim for async locking
+private readonly SemaphoreSlim _semaphore = new(1, 1);
+
+public async Task<User> GetOrCreateUserAsync(int id)
+{
+    await _semaphore.WaitAsync();
+    try
+    {
+        if (!_cache.TryGetValue(id, out var user))
+        {
+            user = await _repository.GetByIdAsync(id);
+            _cache[id] = user;
+        }
+        return user;
+    }
+    finally
+    {
+        _semaphore.Release();
+    }
+}
+
+// BAD - lock with async (will not compile correctly)
+lock (_syncObject)
+{
+    await SomeAsyncOperation();  // Can't await inside lock
+}
+```
+
+## Channel for Producer/Consumer
+
+```csharp
+public class BackgroundProcessor
+{
+    private readonly Channel<WorkItem> _channel =
+        Channel.CreateBounded<WorkItem>(new BoundedChannelOptions(100)
+        {
+            FullMode = BoundedChannelFullMode.Wait
+        });
+
+    public async ValueTask QueueWorkAsync(WorkItem item)
+    {
+        await _channel.Writer.WriteAsync(item);
+    }
+
+    public async Task ProcessAsync(CancellationToken stoppingToken)
+    {
+        await foreach (var item in _channel.Reader.ReadAllAsync(stoppingToken))
+        {
+            await ProcessItemAsync(item);
+        }
+    }
+}
+```