@malamute/ai-rules 1.0.0

package/configs/dotnet/.claude/rules/testing.md

@@ -0,0 +1,389 @@
+---
+paths:
+  - "tests/**/*.cs"
+  - "**/*.Tests/**/*.cs"
+  - "**/*Tests.cs"
+---
+
+# .NET Testing Rules
+
+## Test Project Structure
+
+```
+tests/
+├── Domain.UnitTests/
+│   └── Entities/
+│       └── UserTests.cs
+├── Application.UnitTests/
+│   └── Users/
+│       └── Commands/
+│           └── CreateUserCommandHandlerTests.cs
+├── Infrastructure.IntegrationTests/
+│   └── Repositories/
+│       └── UserRepositoryTests.cs
+└── WebApi.IntegrationTests/
+    └── Endpoints/
+        └── UsersEndpointsTests.cs
+```
+
+## Unit Tests (xUnit + NSubstitute + FluentAssertions)
+
+### Naming Convention
+
+```csharp
+// Method_Scenario_ExpectedResult
+public class UserTests
+{
+    [Fact]
+    public void Create_WithValidEmail_ReturnsUser()
+    {
+        // Arrange
+        var email = "test@example.com";
+        var passwordHash = "hashedPassword";
+
+        // Act
+        var user = User.Create(email, passwordHash);
+
+        // Assert
+        user.Should().NotBeNull();
+        user.Email.Should().Be(email);
+        user.Id.Should().NotBeEmpty();
+    }
+
+    [Fact]
+    public void Create_WithEmptyEmail_ThrowsArgumentException()
+    {
+        // Arrange
+        var email = "";
+        var passwordHash = "hashedPassword";
+
+        // Act
+        var act = () => User.Create(email, passwordHash);
+
+        // Assert
+        act.Should().Throw<ArgumentException>()
+            .WithMessage("*email*");
+    }
+}
+```
+
+### Testing Handlers with Mocks
+
+```csharp
+public class CreateUserCommandHandlerTests
+{
+    private readonly IUserRepository _userRepository;
+    private readonly IPasswordHasher _passwordHasher;
+    private readonly CreateUserCommandHandler _sut;
+
+    public CreateUserCommandHandlerTests()
+    {
+        _userRepository = Substitute.For<IUserRepository>();
+        _passwordHasher = Substitute.For<IPasswordHasher>();
+        _sut = new CreateUserCommandHandler(_userRepository, _passwordHasher);
+    }
+
+    [Fact]
+    public async Task Handle_ValidCommand_CreatesUserAndReturnsId()
+    {
+        // Arrange
+        var command = new CreateUserCommand("test@example.com", "Password123!");
+        _passwordHasher.Hash(command.Password).Returns("hashedPassword");
+
+        // Act
+        var result = await _sut.Handle(command, CancellationToken.None);
+
+        // Assert
+        result.Should().NotBeEmpty();
+        await _userRepository.Received(1).AddAsync(
+            Arg.Is<User>(u => u.Email == command.Email),
+            Arg.Any<CancellationToken>());
+    }
+
+    [Fact]
+    public async Task Handle_ExistingEmail_ThrowsValidationException()
+    {
+        // Arrange
+        var command = new CreateUserCommand("existing@example.com", "Password123!");
+        _userRepository.ExistsAsync(command.Email, Arg.Any<CancellationToken>())
+            .Returns(true);
+
+        // Act
+        var act = () => _sut.Handle(command, CancellationToken.None);
+
+        // Assert
+        await act.Should().ThrowAsync<ValidationException>();
+    }
+}
+```
+
+### Testing Validators
+
+```csharp
+public class CreateUserCommandValidatorTests
+{
+    private readonly CreateUserCommandValidator _sut;
+    private readonly IUserRepository _userRepository;
+
+    public CreateUserCommandValidatorTests()
+    {
+        _userRepository = Substitute.For<IUserRepository>();
+        _sut = new CreateUserCommandValidator(_userRepository);
+    }
+
+    [Theory]
+    [InlineData("")]
+    [InlineData("invalid")]
+    [InlineData("missing@")]
+    public async Task Validate_InvalidEmail_ReturnsError(string email)
+    {
+        // Arrange
+        var command = new CreateUserCommand(email, "Password123!");
+
+        // Act
+        var result = await _sut.ValidateAsync(command);
+
+        // Assert
+        result.IsValid.Should().BeFalse();
+        result.Errors.Should().Contain(e => e.PropertyName == "Email");
+    }
+
+    [Theory]
+    [InlineData("short")]
+    [InlineData("nouppercase1")]
+    [InlineData("NOLOWERCASE1")]
+    [InlineData("NoDigitsHere")]
+    public async Task Validate_WeakPassword_ReturnsError(string password)
+    {
+        // Arrange
+        var command = new CreateUserCommand("test@example.com", password);
+
+        // Act
+        var result = await _sut.ValidateAsync(command);
+
+        // Assert
+        result.IsValid.Should().BeFalse();
+        result.Errors.Should().Contain(e => e.PropertyName == "Password");
+    }
+}
+```
+
+## Integration Tests
+
+### Database Tests with Test Containers
+
+```csharp
+public class UserRepositoryTests : IAsyncLifetime
+{
+    private readonly MsSqlContainer _sqlContainer = new MsSqlBuilder()
+        .WithImage("mcr.microsoft.com/mssql/server:2022-latest")
+        .Build();
+
+    private ApplicationDbContext _context = null!;
+    private UserRepository _sut = null!;
+
+    public async Task InitializeAsync()
+    {
+        await _sqlContainer.StartAsync();
+
+        var options = new DbContextOptionsBuilder<ApplicationDbContext>()
+            .UseSqlServer(_sqlContainer.GetConnectionString())
+            .Options;
+
+        _context = new ApplicationDbContext(options);
+        await _context.Database.MigrateAsync();
+
+        _sut = new UserRepository(_context);
+    }
+
+    public async Task DisposeAsync()
+    {
+        await _context.DisposeAsync();
+        await _sqlContainer.DisposeAsync();
+    }
+
+    [Fact]
+    public async Task AddAsync_ValidUser_PersistsToDatabase()
+    {
+        // Arrange
+        var user = User.Create("test@example.com", "hashedPassword");
+
+        // Act
+        await _sut.AddAsync(user);
+
+        // Assert
+        var savedUser = await _context.Users.FindAsync(user.Id);
+        savedUser.Should().NotBeNull();
+        savedUser!.Email.Should().Be(user.Email);
+    }
+}
+```
+
+### API Integration Tests with WebApplicationFactory
+
+```csharp
+public class UsersEndpointsTests : IClassFixture<WebApplicationFactory<Program>>
+{
+    private readonly HttpClient _client;
+    private readonly WebApplicationFactory<Program> _factory;
+
+    public UsersEndpointsTests(WebApplicationFactory<Program> factory)
+    {
+        _factory = factory.WithWebHostBuilder(builder =>
+        {
+            builder.ConfigureServices(services =>
+            {
+                // Replace real DB with in-memory
+                var descriptor = services.SingleOrDefault(
+                    d => d.ServiceType == typeof(DbContextOptions<ApplicationDbContext>));
+                if (descriptor != null) services.Remove(descriptor);
+
+                services.AddDbContext<ApplicationDbContext>(options =>
+                    options.UseInMemoryDatabase("TestDb"));
+            });
+        });
+
+        _client = _factory.CreateClient();
+    }
+
+    [Fact]
+    public async Task CreateUser_ValidRequest_Returns201()
+    {
+        // Arrange
+        var request = new { Email = "test@example.com", Password = "Password123!" };
+
+        // Act
+        var response = await _client.PostAsJsonAsync("/api/users", request);
+
+        // Assert
+        response.StatusCode.Should().Be(HttpStatusCode.Created);
+        response.Headers.Location.Should().NotBeNull();
+    }
+
+    [Fact]
+    public async Task CreateUser_InvalidEmail_Returns400WithProblemDetails()
+    {
+        // Arrange
+        var request = new { Email = "invalid", Password = "Password123!" };
+
+        // Act
+        var response = await _client.PostAsJsonAsync("/api/users", request);
+
+        // Assert
+        response.StatusCode.Should().Be(HttpStatusCode.BadRequest);
+        var problemDetails = await response.Content.ReadFromJsonAsync<ValidationProblemDetails>();
+        problemDetails!.Errors.Should().ContainKey("Email");
+    }
+
+    [Fact]
+    public async Task GetUser_NonExistent_Returns404()
+    {
+        // Act
+        var response = await _client.GetAsync($"/api/users/{Guid.NewGuid()}");
+
+        // Assert
+        response.StatusCode.Should().Be(HttpStatusCode.NotFound);
+    }
+}
+```
+
+### Authenticated Tests
+
+```csharp
+public class AuthenticatedEndpointsTests : IClassFixture<WebApplicationFactory<Program>>
+{
+    private readonly HttpClient _client;
+
+    public AuthenticatedEndpointsTests(WebApplicationFactory<Program> factory)
+    {
+        _client = factory.WithWebHostBuilder(builder =>
+        {
+            builder.ConfigureServices(services =>
+            {
+                // Add test authentication
+                services.AddAuthentication("Test")
+                    .AddScheme<AuthenticationSchemeOptions, TestAuthHandler>("Test", null);
+            });
+        }).CreateClient();
+
+        _client.DefaultRequestHeaders.Authorization =
+            new AuthenticationHeaderValue("Test");
+    }
+
+    [Fact]
+    public async Task GetProfile_Authenticated_Returns200()
+    {
+        var response = await _client.GetAsync("/api/users/me");
+        response.StatusCode.Should().Be(HttpStatusCode.OK);
+    }
+}
+
+// Test auth handler
+public class TestAuthHandler : AuthenticationHandler<AuthenticationSchemeOptions>
+{
+    public TestAuthHandler(
+        IOptionsMonitor<AuthenticationSchemeOptions> options,
+        ILoggerFactory logger,
+        UrlEncoder encoder)
+        : base(options, logger, encoder) { }
+
+    protected override Task<AuthenticateResult> HandleAuthenticateAsync()
+    {
+        var claims = new[] { new Claim(ClaimTypes.NameIdentifier, Guid.NewGuid().ToString()) };
+        var identity = new ClaimsIdentity(claims, "Test");
+        var principal = new ClaimsPrincipal(identity);
+        var ticket = new AuthenticationTicket(principal, "Test");
+        return Task.FromResult(AuthenticateResult.Success(ticket));
+    }
+}
+```
+
+## Test Data Builders
+
+```csharp
+public class UserBuilder
+{
+    private Guid _id = Guid.NewGuid();
+    private string _email = "default@example.com";
+    private string _passwordHash = "hashedPassword";
+    private string _role = "User";
+
+    public UserBuilder WithId(Guid id) { _id = id; return this; }
+    public UserBuilder WithEmail(string email) { _email = email; return this; }
+    public UserBuilder WithRole(string role) { _role = role; return this; }
+    public UserBuilder AsAdmin() => WithRole("Admin");
+
+    public User Build()
+    {
+        // Use reflection or internal setters for testing
+        return new User
+        {
+            Id = _id,
+            Email = _email,
+            PasswordHash = _passwordHash,
+            Role = _role
+        };
+    }
+}
+
+// Usage
+var user = new UserBuilder()
+    .WithEmail("admin@example.com")
+    .AsAdmin()
+    .Build();
+```
+
+## Code Coverage
+
+```bash
+# Run with coverage
+dotnet test --collect:"XPlat Code Coverage"
+
+# Generate HTML report (requires reportgenerator tool)
+dotnet tool install -g dotnet-reportgenerator-globaltool
+reportgenerator -reports:"**/coverage.cobertura.xml" -targetdir:"coveragereport" -reporttypes:Html
+```
+
+### Coverage Thresholds
+
+Target: **80%+ coverage** on Application and Domain layers.

package/configs/dotnet/.claude/settings.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(dotnet *)",
+      "Bash(dotnet-ef *)"
+    ],
+    "deny": []
+  }
+}

package/configs/dotnet/CLAUDE.md

@@ -0,0 +1,319 @@
+# .NET Project Guidelines
+
+@../_shared/CLAUDE.md
+
+## Stack
+
+- .NET 8+ (latest LTS)
+- ASP.NET Core Web API
+- Entity Framework Core
+- C# 12+ features
+- xUnit for testing
+
+## Architecture
+
+### Clean Architecture (Recommended)
+
+```
+src/
+├── Domain/                        # Core business logic (no dependencies)
+│   ├── Entities/
+│   │   └── User.cs
+│   ├── ValueObjects/
+│   │   └── Email.cs
+│   ├── Enums/
+│   ├── Exceptions/
+│   │   └── DomainException.cs
+│   └── Interfaces/
+│       └── IUserRepository.cs
+│
+├── Application/                   # Use cases, CQRS, DTOs
+│   ├── Common/
+│   │   ├── Behaviors/
+│   │   │   ├── ValidationBehavior.cs
+│   │   │   └── LoggingBehavior.cs
+│   │   ├── Interfaces/
+│   │   │   └── IApplicationDbContext.cs
+│   │   └── Mappings/
+│   │       └── MappingProfile.cs
+│   ├── Users/
+│   │   ├── Commands/
+│   │   │   ├── CreateUser/
+│   │   │   │   ├── CreateUserCommand.cs
+│   │   │   │   ├── CreateUserCommandHandler.cs
+│   │   │   │   └── CreateUserCommandValidator.cs
+│   │   │   └── UpdateUser/
+│   │   └── Queries/
+│   │       ├── GetUser/
+│   │       │   ├── GetUserQuery.cs
+│   │       │   ├── GetUserQueryHandler.cs
+│   │       │   └── UserDto.cs
+│   │       └── GetUsers/
+│   └── DependencyInjection.cs
+│
+├── Infrastructure/                # External concerns
+│   ├── Data/
+│   │   ├── ApplicationDbContext.cs
+│   │   ├── Configurations/
+│   │   │   └── UserConfiguration.cs
+│   │   └── Migrations/
+│   ├── Repositories/
+│   │   └── UserRepository.cs
+│   ├── Services/
+│   │   └── DateTimeService.cs
+│   └── DependencyInjection.cs
+│
+└── WebApi/                        # Presentation layer
+    ├── Controllers/
+    │   └── UsersController.cs
+    ├── Filters/
+    │   └── ApiExceptionFilterAttribute.cs
+    ├── Middleware/
+    │   └── ExceptionHandlingMiddleware.cs
+    ├── Program.cs
+    └── appsettings.json
+```
+
+### Project References
+
+```
+WebApi → Application → Domain
+WebApi → Infrastructure → Application → Domain
+```
+
+**Key rule**: Domain has ZERO external dependencies.
+
+## Code Style
+
+### Naming Conventions
+
+| Element | Convention | Example |
+|---------|------------|---------|
+| Classes | PascalCase | `UserService` |
+| Interfaces | IPascalCase | `IUserRepository` |
+| Methods | PascalCase | `GetUserById` |
+| Properties | PascalCase | `FirstName` |
+| Private fields | _camelCase | `_userRepository` |
+| Parameters | camelCase | `userId` |
+| Constants | PascalCase | `MaxRetryCount` |
+| Async methods | Suffix Async | `GetUserAsync` |
+
+### File-Scoped Namespaces
+
+```csharp
+// Good - C# 10+
+namespace MyApp.Domain.Entities;
+
+public class User { }
+
+// Avoid
+namespace MyApp.Domain.Entities
+{
+    public class User { }
+}
+```
+
+### Primary Constructors (C# 12)
+
+```csharp
+// Good - for simple DI
+public class UserService(IUserRepository userRepository, ILogger<UserService> logger)
+{
+    public async Task<User?> GetByIdAsync(Guid id)
+    {
+        logger.LogInformation("Getting user {UserId}", id);
+        return await userRepository.GetByIdAsync(id);
+    }
+}
+
+// Use traditional constructors when you need field assignment or validation
+```
+
+### Records for DTOs
+
+```csharp
+// Immutable DTOs
+public record UserDto(Guid Id, string Email, string Name);
+
+public record CreateUserRequest(string Email, string Password, string Name);
+
+// With validation attributes
+public record CreateUserCommand(
+    [Required][EmailAddress] string Email,
+    [Required][MinLength(8)] string Password,
+    [Required] string Name
+) : IRequest<Guid>;
+```
+
+### Nullable Reference Types
+
+```csharp
+// Enable in .csproj
+<Nullable>enable</Nullable>
+
+// Be explicit about nullability
+public async Task<User?> GetByIdAsync(Guid id);  // Can return null
+public async Task<User> GetByIdOrThrowAsync(Guid id);  // Never null
+```
+
+## Commands
+
+```bash
+# Development
+dotnet run --project src/WebApi
+
+# Build
+dotnet build
+dotnet publish -c Release
+
+# Tests
+dotnet test
+dotnet test --filter "Category=Unit"
+dotnet test --collect:"XPlat Code Coverage"
+
+# EF Core migrations
+dotnet ef migrations add InitialCreate -p src/Infrastructure -s src/WebApi
+dotnet ef database update -p src/Infrastructure -s src/WebApi
+
+# Format
+dotnet format
+```
+
+## Common Patterns
+
+### Minimal API Endpoints
+
+```csharp
+// Program.cs or endpoint extension
+app.MapGet("/users/{id:guid}", async (Guid id, ISender sender) =>
+{
+    var user = await sender.Send(new GetUserQuery(id));
+    return user is not null ? Results.Ok(user) : Results.NotFound();
+})
+.WithName("GetUser")
+.WithOpenApi()
+.RequireAuthorization();
+
+app.MapPost("/users", async (CreateUserCommand command, ISender sender) =>
+{
+    var id = await sender.Send(command);
+    return Results.CreatedAtRoute("GetUser", new { id }, id);
+})
+.WithName("CreateUser")
+.WithOpenApi();
+```
+
+### Controller-Based API
+
+```csharp
+[ApiController]
+[Route("api/[controller]")]
+public class UsersController(ISender sender) : ControllerBase
+{
+    [HttpGet("{id:guid}")]
+    [ProducesResponseType<UserDto>(StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public async Task<IActionResult> Get(Guid id)
+    {
+        var user = await sender.Send(new GetUserQuery(id));
+        return user is not null ? Ok(user) : NotFound();
+    }
+
+    [HttpPost]
+    [ProducesResponseType<Guid>(StatusCodes.Status201Created)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    public async Task<IActionResult> Create(CreateUserCommand command)
+    {
+        var id = await sender.Send(command);
+        return CreatedAtAction(nameof(Get), new { id }, id);
+    }
+}
+```
+
+### Global Exception Handling
+
+```csharp
+public class ExceptionHandlingMiddleware(RequestDelegate next, ILogger<ExceptionHandlingMiddleware> logger)
+{
+    public async Task InvokeAsync(HttpContext context)
+    {
+        try
+        {
+            await next(context);
+        }
+        catch (ValidationException ex)
+        {
+            context.Response.StatusCode = StatusCodes.Status400BadRequest;
+            await context.Response.WriteAsJsonAsync(new ProblemDetails
+            {
+                Status = 400,
+                Title = "Validation Error",
+                Detail = string.Join(", ", ex.Errors.Select(e => e.ErrorMessage))
+            });
+        }
+        catch (NotFoundException ex)
+        {
+            context.Response.StatusCode = StatusCodes.Status404NotFound;
+            await context.Response.WriteAsJsonAsync(new ProblemDetails
+            {
+                Status = 404,
+                Title = "Not Found",
+                Detail = ex.Message
+            });
+        }
+        catch (Exception ex)
+        {
+            logger.LogError(ex, "Unhandled exception");
+            context.Response.StatusCode = StatusCodes.Status500InternalServerError;
+            await context.Response.WriteAsJsonAsync(new ProblemDetails
+            {
+                Status = 500,
+                Title = "Server Error"
+            });
+        }
+    }
+}
+```
+
+### Dependency Injection Setup
+
+```csharp
+// Application/DependencyInjection.cs
+public static class DependencyInjection
+{
+    public static IServiceCollection AddApplication(this IServiceCollection services)
+    {
+        services.AddMediatR(cfg => {
+            cfg.RegisterServicesFromAssembly(Assembly.GetExecutingAssembly());
+            cfg.AddBehavior(typeof(IPipelineBehavior<,>), typeof(ValidationBehavior<,>));
+            cfg.AddBehavior(typeof(IPipelineBehavior<,>), typeof(LoggingBehavior<,>));
+        });
+
+        services.AddValidatorsFromAssembly(Assembly.GetExecutingAssembly());
+        services.AddAutoMapper(Assembly.GetExecutingAssembly());
+
+        return services;
+    }
+}
+
+// Infrastructure/DependencyInjection.cs
+public static class DependencyInjection
+{
+    public static IServiceCollection AddInfrastructure(this IServiceCollection services, IConfiguration configuration)
+    {
+        services.AddDbContext<ApplicationDbContext>(options =>
+            options.UseSqlServer(configuration.GetConnectionString("DefaultConnection")));
+
+        services.AddScoped<IApplicationDbContext>(sp =>
+            sp.GetRequiredService<ApplicationDbContext>());
+
+        services.AddScoped<IUserRepository, UserRepository>();
+
+        return services;
+    }
+}
+
+// Program.cs
+builder.Services.AddApplication();
+builder.Services.AddInfrastructure(builder.Configuration);
+```