@malamute/ai-rules 1.0.0

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

@@ -0,0 +1,315 @@
+---
+paths:
+  - "src/**/*.spec.ts"
+  - "test/**/*.e2e-spec.ts"
+---
+
+# NestJS Testing
+
+## Unit Tests
+
+### Test Services in Isolation
+
+Mock all dependencies. Focus on business logic.
+
+```typescript
+import { Test, TestingModule } from '@nestjs/testing';
+import { UsersService } from './users.service';
+import { UsersRepository } from './users.repository';
+import { NotFoundException } from '@nestjs/common';
+
+describe('UsersService', () => {
+  let service: UsersService;
+  let repository: jest.Mocked<UsersRepository>;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        UsersService,
+        {
+          provide: UsersRepository,
+          useValue: {
+            findById: jest.fn(),
+            create: jest.fn(),
+            update: jest.fn(),
+            delete: jest.fn(),
+          },
+        },
+      ],
+    }).compile();
+
+    service = module.get<UsersService>(UsersService);
+    repository = module.get(UsersRepository);
+  });
+
+  describe('findOne', () => {
+    it('should return user when found', async () => {
+      const user = { id: '1', email: 'test@example.com' };
+      repository.findById.mockResolvedValue(user);
+
+      const result = await service.findOne('1');
+
+      expect(result).toEqual(user);
+      expect(repository.findById).toHaveBeenCalledWith('1');
+    });
+
+    it('should throw NotFoundException when user not found', async () => {
+      repository.findById.mockResolvedValue(null);
+
+      await expect(service.findOne('1')).rejects.toThrow(NotFoundException);
+    });
+  });
+});
+```
+
+### Test Controllers
+
+Test request handling, pipes, guards.
+
+```typescript
+import { Test, TestingModule } from '@nestjs/testing';
+import { UsersController } from './users.controller';
+import { UsersService } from './users.service';
+
+describe('UsersController', () => {
+  let controller: UsersController;
+  let service: jest.Mocked<UsersService>;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      controllers: [UsersController],
+      providers: [
+        {
+          provide: UsersService,
+          useValue: {
+            findOne: jest.fn(),
+            create: jest.fn(),
+          },
+        },
+      ],
+    }).compile();
+
+    controller = module.get<UsersController>(UsersController);
+    service = module.get(UsersService);
+  });
+
+  describe('findOne', () => {
+    it('should return user from service', async () => {
+      const user = { id: '1', email: 'test@example.com' };
+      service.findOne.mockResolvedValue(user);
+
+      const result = await controller.findOne('1');
+
+      expect(result).toEqual(user);
+      expect(service.findOne).toHaveBeenCalledWith('1');
+    });
+  });
+});
+```
+
+### Mock Repository Pattern
+
+```typescript
+// Create reusable mock factory
+export const createMockRepository = <T = any>() => ({
+  find: jest.fn(),
+  findOne: jest.fn(),
+  create: jest.fn(),
+  save: jest.fn(),
+  update: jest.fn(),
+  delete: jest.fn(),
+  createQueryBuilder: jest.fn(() => ({
+    where: jest.fn().mockReturnThis(),
+    andWhere: jest.fn().mockReturnThis(),
+    orderBy: jest.fn().mockReturnThis(),
+    skip: jest.fn().mockReturnThis(),
+    take: jest.fn().mockReturnThis(),
+    getMany: jest.fn(),
+    getOne: jest.fn(),
+  })),
+});
+
+// Usage
+const module = await Test.createTestingModule({
+  providers: [
+    UsersService,
+    {
+      provide: getRepositoryToken(User),
+      useValue: createMockRepository(),
+    },
+  ],
+}).compile();
+```
+
+## E2E Tests
+
+### Setup Test Application
+
+```typescript
+// test/app.e2e-spec.ts
+import { Test, TestingModule } from '@nestjs/testing';
+import { INestApplication, ValidationPipe } from '@nestjs/common';
+import * as request from 'supertest';
+import { AppModule } from '../src/app.module';
+
+describe('AppController (e2e)', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    const moduleFixture: TestingModule = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    app = moduleFixture.createNestApplication();
+
+    // Apply same pipes as production
+    app.useGlobalPipes(
+      new ValidationPipe({
+        whitelist: true,
+        forbidNonWhitelisted: true,
+        transform: true,
+      }),
+    );
+
+    await app.init();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  describe('/users', () => {
+    it('POST /users - should create user', () => {
+      return request(app.getHttpServer())
+        .post('/users')
+        .send({
+          email: 'test@example.com',
+          password: 'password123',
+        })
+        .expect(201)
+        .expect((res) => {
+          expect(res.body).toHaveProperty('id');
+          expect(res.body.email).toBe('test@example.com');
+        });
+    });
+
+    it('POST /users - should reject invalid email', () => {
+      return request(app.getHttpServer())
+        .post('/users')
+        .send({
+          email: 'invalid-email',
+          password: 'password123',
+        })
+        .expect(400);
+    });
+
+    it('GET /users/:id - should return user', () => {
+      return request(app.getHttpServer())
+        .get('/users/existing-id')
+        .expect(200)
+        .expect((res) => {
+          expect(res.body).toHaveProperty('email');
+        });
+    });
+
+    it('GET /users/:id - should return 404 for unknown user', () => {
+      return request(app.getHttpServer())
+        .get('/users/unknown-id')
+        .expect(404);
+    });
+  });
+});
+```
+
+### Test with Authentication
+
+```typescript
+describe('Protected Routes (e2e)', () => {
+  let app: INestApplication;
+  let authToken: string;
+
+  beforeAll(async () => {
+    // ... setup app
+
+    // Get auth token
+    const response = await request(app.getHttpServer())
+      .post('/auth/login')
+      .send({ email: 'test@example.com', password: 'password' });
+
+    authToken = response.body.accessToken;
+  });
+
+  it('GET /profile - should return user profile with token', () => {
+    return request(app.getHttpServer())
+      .get('/profile')
+      .set('Authorization', `Bearer ${authToken}`)
+      .expect(200);
+  });
+
+  it('GET /profile - should return 401 without token', () => {
+    return request(app.getHttpServer())
+      .get('/profile')
+      .expect(401);
+  });
+});
+```
+
+### Test Database Isolation
+
+Use a test database and clean between tests:
+
+```typescript
+import { DataSource } from 'typeorm';
+
+describe('Users E2E', () => {
+  let app: INestApplication;
+  let dataSource: DataSource;
+
+  beforeAll(async () => {
+    const module = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    app = module.createNestApplication();
+    await app.init();
+
+    dataSource = module.get(DataSource);
+  });
+
+  beforeEach(async () => {
+    // Clean database before each test
+    await dataSource.synchronize(true);
+  });
+
+  afterAll(async () => {
+    await dataSource.destroy();
+    await app.close();
+  });
+});
+```
+
+## Test Coverage Goals
+
+- **Services**: 90%+ (business logic)
+- **Controllers**: 80%+ (happy paths + error cases)
+- **Guards/Pipes**: 80%+
+- **E2E**: Cover all API endpoints
+
+## Testing Commands
+
+```bash
+# Unit tests
+npm run test
+
+# Watch mode
+npm run test:watch
+
+# Coverage report
+npm run test:cov
+
+# E2E tests
+npm run test:e2e
+
+# Single file
+npm run test -- users.service.spec.ts
+```

package/configs/nestjs/.claude/rules/validation.md

@@ -0,0 +1,279 @@
+---
+paths:
+  - "src/**/*.dto.ts"
+  - "src/**/dto/*.ts"
+---
+
+# NestJS Validation & DTOs
+
+## DTO Rules
+
+### Always Use class-validator
+
+Every DTO property must have validation decorators.
+
+```typescript
+import {
+  IsEmail,
+  IsString,
+  IsOptional,
+  MinLength,
+  MaxLength,
+  IsUUID,
+  IsEnum,
+  IsArray,
+  ValidateNested,
+  IsInt,
+  Min,
+  Max,
+} from 'class-validator';
+import { Type } from 'class-transformer';
+
+export class CreateUserDto {
+  @IsEmail()
+  email: string;
+
+  @IsString()
+  @MinLength(8)
+  @MaxLength(100)
+  password: string;
+
+  @IsString()
+  @IsOptional()
+  @MaxLength(50)
+  name?: string;
+
+  @IsEnum(UserRole)
+  @IsOptional()
+  role?: UserRole;
+}
+```
+
+### Use Mapped Types for Variants
+
+```typescript
+import { PartialType, PickType, OmitType, IntersectionType } from '@nestjs/mapped-types';
+
+// All fields optional
+export class UpdateUserDto extends PartialType(CreateUserDto) {}
+
+// Only specific fields
+export class LoginDto extends PickType(CreateUserDto, ['email', 'password']) {}
+
+// Exclude fields
+export class PublicUserDto extends OmitType(CreateUserDto, ['password']) {}
+
+// Combine DTOs
+export class CreateUserWithAddressDto extends IntersectionType(
+  CreateUserDto,
+  CreateAddressDto,
+) {}
+```
+
+### Validate Nested Objects
+
+```typescript
+export class CreateOrderDto {
+  @IsUUID()
+  userId: string;
+
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => OrderItemDto)
+  items: OrderItemDto[];
+
+  @ValidateNested()
+  @Type(() => AddressDto)
+  shippingAddress: AddressDto;
+}
+
+export class OrderItemDto {
+  @IsUUID()
+  productId: string;
+
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  quantity: number;
+}
+```
+
+### Transform Input Data
+
+```typescript
+import { Transform, Type } from 'class-transformer';
+
+export class QueryDto {
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  page?: number = 1;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  limit?: number = 20;
+
+  @IsOptional()
+  @Transform(({ value }) => value?.toLowerCase().trim())
+  @IsString()
+  search?: string;
+
+  @IsOptional()
+  @Transform(({ value }) => value === 'true' || value === true)
+  @IsBoolean()
+  active?: boolean;
+}
+```
+
+## Validation Groups
+
+Use groups for conditional validation:
+
+```typescript
+export class UserDto {
+  @IsUUID({ groups: ['update'] })
+  @IsOptional({ groups: ['create'] })
+  id?: string;
+
+  @IsEmail({ groups: ['create', 'update'] })
+  email: string;
+
+  @IsString({ groups: ['create'] })
+  @MinLength(8, { groups: ['create'] })
+  password: string;
+}
+
+// Controller usage
+@Post()
+create(
+  @Body(new ValidationPipe({ groups: ['create'] }))
+  dto: UserDto,
+) {}
+
+@Patch(':id')
+update(
+  @Body(new ValidationPipe({ groups: ['update'] }))
+  dto: UserDto,
+) {}
+```
+
+## Custom Validators
+
+```typescript
+import {
+  ValidatorConstraint,
+  ValidatorConstraintInterface,
+  ValidationArguments,
+  registerDecorator,
+} from 'class-validator';
+
+@ValidatorConstraint({ async: true })
+export class IsUniqueEmailConstraint implements ValidatorConstraintInterface {
+  constructor(private readonly usersService: UsersService) {}
+
+  async validate(email: string): Promise<boolean> {
+    const user = await this.usersService.findByEmail(email);
+    return !user;
+  }
+
+  defaultMessage(args: ValidationArguments): string {
+    return 'Email already exists';
+  }
+}
+
+// Decorator factory
+export function IsUniqueEmail(validationOptions?: ValidationOptions) {
+  return function (object: object, propertyName: string) {
+    registerDecorator({
+      target: object.constructor,
+      propertyName,
+      options: validationOptions,
+      constraints: [],
+      validator: IsUniqueEmailConstraint,
+    });
+  };
+}
+
+// Usage
+export class CreateUserDto {
+  @IsEmail()
+  @IsUniqueEmail()
+  email: string;
+}
+```
+
+## API Documentation with Swagger
+
+Combine validation with OpenAPI documentation:
+
+```typescript
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+export class CreateUserDto {
+  @ApiProperty({
+    example: 'user@example.com',
+    description: 'User email address',
+  })
+  @IsEmail()
+  email: string;
+
+  @ApiProperty({
+    minLength: 8,
+    description: 'User password (min 8 characters)',
+  })
+  @IsString()
+  @MinLength(8)
+  password: string;
+
+  @ApiPropertyOptional({
+    example: 'John Doe',
+    maxLength: 50,
+  })
+  @IsString()
+  @IsOptional()
+  @MaxLength(50)
+  name?: string;
+}
+```
+
+## Response DTOs
+
+Use separate DTOs for responses to control exposed data:
+
+```typescript
+import { Exclude, Expose, Type } from 'class-transformer';
+
+export class UserResponseDto {
+  @Expose()
+  id: string;
+
+  @Expose()
+  email: string;
+
+  @Expose()
+  name: string;
+
+  @Exclude()
+  password: string;
+
+  @Expose()
+  @Type(() => Date)
+  createdAt: Date;
+
+  constructor(partial: Partial<UserResponseDto>) {
+    Object.assign(this, partial);
+  }
+}
+
+// Service usage with ClassSerializerInterceptor
+@UseInterceptors(ClassSerializerInterceptor)
+@Get(':id')
+async findOne(@Param('id') id: string): Promise<UserResponseDto> {
+  const user = await this.usersService.findOne(id);
+  return new UserResponseDto(user);
+}
+```

package/configs/nestjs/.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run start:dev)",
+      "Bash(npm run build)",
+      "Bash(npm run test*)",
+      "Bash(npm run lint*)",
+      "Bash(npm run format*)",
+      "Bash(npx prisma *)",
+      "Bash(npx typeorm *)",
+      "Bash(npm install *)"
+    ],
+    "deny": []
+  }
+}