@malamute/ai-rules 1.0.0 → 1.2.0

package/configs/_shared/.claude/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);
+        }
+    }
+}
+```

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

@@ -0,0 +1,314 @@
+---
+paths:
+  - "**/*.cs"
+  - "**/*.csproj"
+---
+
+# C# Code Style Rules
+
+## Nullability
+
+Enable nullable reference types in all projects:
+
+```xml
+<PropertyGroup>
+  <Nullable>enable</Nullable>
+</PropertyGroup>
+```
+
+```csharp
+// GOOD - explicit nullability
+public string Name { get; set; } = string.Empty;
+public string? MiddleName { get; set; }
+
+// BAD - ambiguous
+public string Name { get; set; }  // Warning: non-nullable not initialized
+```
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|------------|---------|
+| Classes | PascalCase | `UserService` |
+| Interfaces | IPascalCase | `IUserRepository` |
+| Methods | PascalCase | `GetUserById` |
+| Properties | PascalCase | `FirstName` |
+| Private fields | _camelCase | `_userRepository` |
+| Local variables | camelCase | `currentUser` |
+| Constants | PascalCase | `MaxRetryCount` |
+| Async methods | Suffix `Async` | `GetUserAsync` |
+
+```csharp
+// GOOD
+private readonly IUserRepository _userRepository;
+public async Task<User?> GetUserByIdAsync(int id) { }
+
+// BAD
+private IUserRepository userRepository;  // Missing underscore
+public async Task<User?> GetUserById(int id) { }  // Missing Async suffix
+```
+
+## Type Guidelines
+
+### Use `var` When Type Is Obvious
+
+```csharp
+// GOOD - type is obvious
+var user = new User();
+var users = await _repository.GetAllAsync();
+var count = items.Count;
+
+// GOOD - type not obvious, be explicit
+User user = GetUser();
+IEnumerable<string> names = GetNames();
+
+// BAD - redundant
+User user = new User();
+```
+
+### Prefer Collection Expressions (C# 12+)
+
+```csharp
+// GOOD - collection expressions
+int[] numbers = [1, 2, 3];
+List<string> names = ["Alice", "Bob"];
+Dictionary<string, int> ages = new() { ["Alice"] = 30 };
+
+// BAD - verbose
+int[] numbers = new int[] { 1, 2, 3 };
+List<string> names = new List<string> { "Alice", "Bob" };
+```
+
+### Use Pattern Matching
+
+```csharp
+// GOOD - pattern matching
+if (user is { IsActive: true, Role: "Admin" })
+{
+    // ...
+}
+
+return status switch
+{
+    OrderStatus.Pending => "Awaiting payment",
+    OrderStatus.Shipped => "On the way",
+    OrderStatus.Delivered => "Completed",
+    _ => "Unknown"
+};
+
+// BAD - verbose checks
+if (user != null && user.IsActive && user.Role == "Admin")
+```
+
+## Async/Await
+
+### Always Use Async All The Way
+
+```csharp
+// GOOD - async all the way
+public async Task<User> GetUserAsync(int id)
+{
+    return await _repository.GetByIdAsync(id);
+}
+
+// BAD - blocking on async
+public User GetUser(int id)
+{
+    return _repository.GetByIdAsync(id).Result;  // Deadlock risk!
+}
+
+// BAD - async void (except event handlers)
+public async void ProcessData()  // Can't await, exceptions lost
+```
+
+### ConfigureAwait in Libraries
+
+```csharp
+// In library code (not ASP.NET Core)
+await SomeOperationAsync().ConfigureAwait(false);
+
+// In ASP.NET Core controllers - not needed
+await SomeOperationAsync();
+```
+
+### Cancellation Tokens
+
+```csharp
+// GOOD - propagate cancellation
+public async Task<List<User>> GetUsersAsync(CancellationToken cancellationToken = default)
+{
+    return await _context.Users
+        .Where(u => u.IsActive)
+        .ToListAsync(cancellationToken);
+}
+
+// BAD - ignoring cancellation
+public async Task<List<User>> GetUsersAsync()
+{
+    return await _context.Users.ToListAsync();
+}
+```
+
+## LINQ Best Practices
+
+```csharp
+// GOOD - method syntax for complex queries
+var activeAdmins = users
+    .Where(u => u.IsActive)
+    .Where(u => u.Role == Role.Admin)
+    .OrderBy(u => u.Name)
+    .Select(u => new UserDto(u.Id, u.Name))
+    .ToList();
+
+// GOOD - query syntax for joins
+var result = from order in orders
+             join customer in customers on order.CustomerId equals customer.Id
+             select new { order.Id, customer.Name };
+
+// BAD - multiple enumerations
+var users = GetUsers();
+var count = users.Count();      // First enumeration
+var first = users.First();       // Second enumeration
+
+// GOOD - materialize once
+var users = GetUsers().ToList();
+var count = users.Count;
+var first = users[0];
+```
+
+## Records and Immutability
+
+```csharp
+// GOOD - immutable DTOs with records
+public record UserDto(int Id, string Name, string Email);
+
+public record CreateUserCommand(string Name, string Email)
+{
+    public DateTime CreatedAt { get; init; } = DateTime.UtcNow;
+}
+
+// GOOD - with-expressions for modifications
+var updated = user with { Name = "New Name" };
+
+// BAD - mutable DTOs
+public class UserDto
+{
+    public int Id { get; set; }
+    public string Name { get; set; }
+}
+```
+
+## Error Handling
+
+### Specific Exceptions
+
+```csharp
+// GOOD - specific exceptions
+public User GetUser(int id)
+{
+    return _repository.GetById(id)
+        ?? throw new NotFoundException($"User {id} not found");
+}
+
+// BAD - generic exception
+throw new Exception("User not found");
+```
+
+### Never Swallow Exceptions
+
+```csharp
+// BAD - silent failure
+try
+{
+    await _service.ProcessAsync();
+}
+catch (Exception)
+{
+    // Swallowed
+}
+
+// GOOD - log and handle
+try
+{
+    await _service.ProcessAsync();
+}
+catch (Exception ex)
+{
+    _logger.LogError(ex, "Failed to process");
+    throw;
+}
+```
+
+## Disposables
+
+```csharp
+// GOOD - using declaration (C# 8+)
+await using var connection = new SqlConnection(connectionString);
+await connection.OpenAsync();
+
+// GOOD - using statement for limited scope
+using (var stream = File.OpenRead(path))
+{
+    // ...
+}
+// Stream disposed here
+
+// BAD - manual disposal
+var connection = new SqlConnection(connectionString);
+try
+{
+    await connection.OpenAsync();
+}
+finally
+{
+    connection.Dispose();
+}
+```
+
+## File-Scoped Namespaces
+
+```csharp
+// GOOD - file-scoped (C# 10+)
+namespace MyApp.Services;
+
+public class UserService
+{
+    // ...
+}
+
+// BAD - block-scoped (unnecessary nesting)
+namespace MyApp.Services
+{
+    public class UserService
+    {
+        // ...
+    }
+}
+```
+
+## Primary Constructors (C# 12+)
+
+```csharp
+// GOOD - primary constructor
+public class UserService(IUserRepository repository, ILogger<UserService> logger)
+{
+    public async Task<User?> GetUserAsync(int id)
+    {
+        logger.LogInformation("Getting user {Id}", id);
+        return await repository.GetByIdAsync(id);
+    }
+}
+
+// Also valid - traditional constructor with readonly fields
+public class UserService
+{
+    private readonly IUserRepository _repository;
+    private readonly ILogger<UserService> _logger;
+
+    public UserService(IUserRepository repository, ILogger<UserService> logger)
+    {
+        _repository = repository;
+        _logger = logger;
+    }
+}
+```