@malamute/ai-rules 1.0.0 → 1.3.0

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

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

@@ -0,0 +1,210 @@
+---
+paths:
+  - "**/*.cs"
+---
+
+# LINQ Best Practices
+
+## Method vs Query Syntax
+
+```csharp
+// Method syntax - preferred for simple queries
+var activeUsers = users
+    .Where(u => u.IsActive)
+    .OrderBy(u => u.Name)
+    .ToList();
+
+// Query syntax - better for joins and complex queries
+var orderDetails = from order in orders
+                   join customer in customers
+                       on order.CustomerId equals customer.Id
+                   join product in products
+                       on order.ProductId equals product.Id
+                   where order.Status == OrderStatus.Completed
+                   select new
+                   {
+                       OrderId = order.Id,
+                       CustomerName = customer.Name,
+                       ProductName = product.Name
+                   };
+```
+
+## Deferred vs Immediate Execution
+
+```csharp
+// Deferred - query not executed until enumerated
+var query = users.Where(u => u.IsActive);  // No DB call yet
+
+// Immediate - forces execution
+var list = users.Where(u => u.IsActive).ToList();      // Executes now
+var array = users.Where(u => u.IsActive).ToArray();    // Executes now
+var first = users.First(u => u.IsActive);              // Executes now
+var count = users.Count(u => u.IsActive);              // Executes now
+
+// BAD - multiple enumeration
+IEnumerable<User> users = GetUsers();
+if (users.Any())           // First enumeration
+{
+    var first = users.First();  // Second enumeration - might get different data!
+}
+
+// GOOD - materialize once
+var users = GetUsers().ToList();
+if (users.Count > 0)
+{
+    var first = users[0];
+}
+```
+
+## Filtering
+
+```csharp
+// Chain Where for readability
+var results = items
+    .Where(x => x.IsActive)
+    .Where(x => x.Category == "Electronics")
+    .Where(x => x.Price > 100);
+
+// Use Any/All for existence checks
+if (users.Any(u => u.Role == Role.Admin))  // GOOD
+if (users.Where(u => u.Role == Role.Admin).Count() > 0)  // BAD
+
+// FirstOrDefault with predicate
+var admin = users.FirstOrDefault(u => u.Role == Role.Admin);
+
+// SingleOrDefault when expecting 0 or 1
+var user = users.SingleOrDefault(u => u.Email == email);
+```
+
+## Projection
+
+```csharp
+// Select for transformation
+var dtos = users.Select(u => new UserDto(u.Id, u.Name));
+
+// SelectMany to flatten
+var allOrders = customers.SelectMany(c => c.Orders);
+
+// Anonymous types for intermediate results
+var intermediate = users
+    .Select(u => new { u.Id, FullName = $"{u.FirstName} {u.LastName}" })
+    .Where(x => x.FullName.StartsWith("A"));
+```
+
+## Grouping
+
+```csharp
+// GroupBy
+var usersByRole = users
+    .GroupBy(u => u.Role)
+    .Select(g => new
+    {
+        Role = g.Key,
+        Count = g.Count(),
+        Users = g.ToList()
+    });
+
+// ToLookup - immediate execution, allows multiple enumeration
+var lookup = users.ToLookup(u => u.Role);
+var admins = lookup[Role.Admin];
+var managers = lookup[Role.Manager];
+```
+
+## Aggregation
+
+```csharp
+// Aggregate functions
+var total = orders.Sum(o => o.Amount);
+var average = orders.Average(o => o.Amount);
+var max = orders.Max(o => o.Amount);
+var min = orders.Min(o => o.Amount);
+
+// Aggregate for custom accumulation
+var concatenated = names.Aggregate((a, b) => $"{a}, {b}");
+
+// With seed value
+var total = items.Aggregate(
+    seed: 0m,
+    func: (sum, item) => sum + item.Price * item.Quantity);
+```
+
+## Set Operations
+
+```csharp
+// Distinct
+var uniqueCategories = products.Select(p => p.Category).Distinct();
+
+// DistinctBy (C# 10+)
+var uniqueByName = products.DistinctBy(p => p.Name);
+
+// Union, Intersect, Except
+var allIds = list1.Select(x => x.Id).Union(list2.Select(x => x.Id));
+var commonIds = list1.Select(x => x.Id).Intersect(list2.Select(x => x.Id));
+var onlyInFirst = list1.Select(x => x.Id).Except(list2.Select(x => x.Id));
+```
+
+## Ordering
+
+```csharp
+// Multiple sort criteria
+var sorted = users
+    .OrderBy(u => u.LastName)
+    .ThenBy(u => u.FirstName)
+    .ThenByDescending(u => u.CreatedAt);
+
+// Order vs OrderBy (C# 11+)
+var ordered = items.Order();  // Uses default comparer
+var orderedDesc = items.OrderDescending();
+```
+
+## Pagination
+
+```csharp
+// Skip/Take for pagination
+var page = users
+    .OrderBy(u => u.Id)
+    .Skip((pageNumber - 1) * pageSize)
+    .Take(pageSize)
+    .ToList();
+
+// Chunk for batching (C# 10+)
+var batches = items.Chunk(100);
+foreach (var batch in batches)
+{
+    await ProcessBatchAsync(batch);
+}
+```
+
+## EF Core Specific
+
+```csharp
+// GOOD - let EF translate to SQL
+var users = await _context.Users
+    .Where(u => u.IsActive)
+    .OrderBy(u => u.Name)
+    .ToListAsync();
+
+// BAD - client-side evaluation (throws in EF Core 3+)
+var users = await _context.Users
+    .Where(u => SomeLocalMethod(u))  // Can't translate
+    .ToListAsync();
+
+// GOOD - explicit client evaluation when needed
+var users = await _context.Users
+    .Where(u => u.IsActive)
+    .AsEnumerable()  // Switch to client
+    .Where(u => SomeLocalMethod(u))
+    .ToList();
+
+// Use AsNoTracking for read-only queries
+var users = await _context.Users
+    .AsNoTracking()
+    .Where(u => u.IsActive)
+    .ToListAsync();
+
+// Projection to avoid over-fetching
+var dtos = await _context.Users
+    .Where(u => u.IsActive)
+    .Select(u => new UserDto(u.Id, u.Name, u.Email))
+    .ToListAsync();
+```