@malamute/ai-rules 1.0.0 → 1.3.0

package/configs/nestjs/rules/middleware.md

@@ -0,0 +1,321 @@
+---
+paths:
+  - "**/*.middleware.ts"
+  - "**/middleware/**/*.ts"
+---
+
+# NestJS Middleware
+
+## Functional Middleware
+
+```typescript
+// middleware/logger.middleware.ts
+import { Request, Response, NextFunction } from 'express';
+
+export function loggerMiddleware(req: Request, res: Response, next: NextFunction) {
+  const start = Date.now();
+
+  res.on('finish', () => {
+    const duration = Date.now() - start;
+    console.log(`${req.method} ${req.url} ${res.statusCode} - ${duration}ms`);
+  });
+
+  next();
+}
+
+// Apply in module
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer.apply(loggerMiddleware).forRoutes('*');
+  }
+}
+```
+
+## Class Middleware
+
+```typescript
+// middleware/auth.middleware.ts
+import { Injectable, NestMiddleware, UnauthorizedException } from '@nestjs/common';
+import { Request, Response, NextFunction } from 'express';
+import { JwtService } from '@nestjs/jwt';
+
+@Injectable()
+export class AuthMiddleware implements NestMiddleware {
+  constructor(private readonly jwtService: JwtService) {}
+
+  async use(req: Request, res: Response, next: NextFunction) {
+    const authHeader = req.headers.authorization;
+
+    if (!authHeader?.startsWith('Bearer ')) {
+      throw new UnauthorizedException('Missing token');
+    }
+
+    const token = authHeader.split(' ')[1];
+
+    try {
+      const payload = await this.jwtService.verifyAsync(token);
+      req['user'] = payload;
+      next();
+    } catch {
+      throw new UnauthorizedException('Invalid token');
+    }
+  }
+}
+```
+
+## Correlation ID Middleware
+
+```typescript
+// middleware/correlation-id.middleware.ts
+import { Injectable, NestMiddleware } from '@nestjs/common';
+import { Request, Response, NextFunction } from 'express';
+import { randomUUID } from 'crypto';
+
+@Injectable()
+export class CorrelationIdMiddleware implements NestMiddleware {
+  use(req: Request, res: Response, next: NextFunction) {
+    const correlationId = req.headers['x-correlation-id'] as string || randomUUID();
+
+    req['correlationId'] = correlationId;
+    res.setHeader('x-correlation-id', correlationId);
+
+    next();
+  }
+}
+```
+
+## Request Validation Middleware
+
+```typescript
+// middleware/content-type.middleware.ts
+import { Injectable, NestMiddleware, UnsupportedMediaTypeException } from '@nestjs/common';
+import { Request, Response, NextFunction } from 'express';
+
+@Injectable()
+export class JsonContentTypeMiddleware implements NestMiddleware {
+  use(req: Request, res: Response, next: NextFunction) {
+    if (['POST', 'PUT', 'PATCH'].includes(req.method)) {
+      const contentType = req.headers['content-type'];
+
+      if (!contentType?.includes('application/json')) {
+        throw new UnsupportedMediaTypeException('Content-Type must be application/json');
+      }
+    }
+
+    next();
+  }
+}
+```
+
+## Rate Limiting Middleware
+
+```typescript
+// middleware/rate-limit.middleware.ts
+import { Injectable, NestMiddleware, HttpException, HttpStatus } from '@nestjs/common';
+import { Request, Response, NextFunction } from 'express';
+import { Redis } from 'ioredis';
+
+@Injectable()
+export class RateLimitMiddleware implements NestMiddleware {
+  private readonly windowMs = 60 * 1000; // 1 minute
+  private readonly maxRequests = 100;
+
+  constructor(private readonly redis: Redis) {}
+
+  async use(req: Request, res: Response, next: NextFunction) {
+    const key = `rate-limit:${req.ip}`;
+    const current = await this.redis.incr(key);
+
+    if (current === 1) {
+      await this.redis.pexpire(key, this.windowMs);
+    }
+
+    const remaining = Math.max(0, this.maxRequests - current);
+    const ttl = await this.redis.pttl(key);
+
+    res.setHeader('X-RateLimit-Limit', this.maxRequests);
+    res.setHeader('X-RateLimit-Remaining', remaining);
+    res.setHeader('X-RateLimit-Reset', Math.ceil(Date.now() / 1000 + ttl / 1000));
+
+    if (current > this.maxRequests) {
+      throw new HttpException('Too Many Requests', HttpStatus.TOO_MANY_REQUESTS);
+    }
+
+    next();
+  }
+}
+```
+
+## Request Sanitization Middleware
+
+```typescript
+// middleware/sanitize.middleware.ts
+import { Injectable, NestMiddleware } from '@nestjs/common';
+import { Request, Response, NextFunction } from 'express';
+import * as sanitizeHtml from 'sanitize-html';
+
+@Injectable()
+export class SanitizeMiddleware implements NestMiddleware {
+  use(req: Request, res: Response, next: NextFunction) {
+    if (req.body) {
+      req.body = this.sanitizeObject(req.body);
+    }
+
+    next();
+  }
+
+  private sanitizeObject(obj: Record<string, unknown>): Record<string, unknown> {
+    const sanitized: Record<string, unknown> = {};
+
+    for (const [key, value] of Object.entries(obj)) {
+      if (typeof value === 'string') {
+        sanitized[key] = sanitizeHtml(value, {
+          allowedTags: [],
+          allowedAttributes: {},
+        });
+      } else if (typeof value === 'object' && value !== null) {
+        sanitized[key] = this.sanitizeObject(value as Record<string, unknown>);
+      } else {
+        sanitized[key] = value;
+      }
+    }
+
+    return sanitized;
+  }
+}
+```
+
+## Applying Middleware
+
+```typescript
+// app.module.ts
+import { Module, NestModule, MiddlewareConsumer, RequestMethod } from '@nestjs/common';
+
+@Module({})
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    // Apply to all routes
+    consumer.apply(CorrelationIdMiddleware).forRoutes('*');
+
+    // Apply to specific path
+    consumer.apply(AuthMiddleware).forRoutes('api/protected');
+
+    // Apply to specific controller
+    consumer.apply(LoggerMiddleware).forRoutes(UsersController);
+
+    // Apply with method filter
+    consumer
+      .apply(JsonContentTypeMiddleware)
+      .forRoutes({ path: '*', method: RequestMethod.POST });
+
+    // Exclude routes
+    consumer
+      .apply(AuthMiddleware)
+      .exclude(
+        { path: 'auth/login', method: RequestMethod.POST },
+        { path: 'auth/register', method: RequestMethod.POST },
+        { path: 'health', method: RequestMethod.GET },
+      )
+      .forRoutes('*');
+
+    // Chain multiple middleware
+    consumer
+      .apply(CorrelationIdMiddleware, LoggerMiddleware, AuthMiddleware)
+      .forRoutes('api');
+  }
+}
+```
+
+## Global Middleware (Express)
+
+```typescript
+// main.ts
+import * as helmet from 'helmet';
+import * as compression from 'compression';
+import * as cookieParser from 'cookie-parser';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  // Security headers
+  app.use(helmet());
+
+  // Compression
+  app.use(compression());
+
+  // Cookie parsing
+  app.use(cookieParser());
+
+  // CORS
+  app.enableCors({
+    origin: process.env.ALLOWED_ORIGINS?.split(',') || '*',
+    credentials: true,
+  });
+
+  // Body parsing limits
+  app.use(express.json({ limit: '10mb' }));
+  app.use(express.urlencoded({ extended: true, limit: '10mb' }));
+
+  await app.listen(3000);
+}
+```
+
+## Middleware vs Guards vs Interceptors
+
+| Feature | Middleware | Guards | Interceptors |
+|---------|------------|--------|--------------|
+| Execution Order | First | After middleware | After guards |
+| Access to ExecutionContext | No | Yes | Yes |
+| Can transform response | No | No | Yes |
+| DI support | Class only | Yes | Yes |
+| Use case | Request processing | Authorization | Transform/logging |
+
+## Anti-patterns
+
+```typescript
+// BAD: Heavy operations in middleware
+@Injectable()
+export class HeavyMiddleware implements NestMiddleware {
+  async use(req: Request, res: Response, next: NextFunction) {
+    await this.db.query('SELECT * FROM logs'); // Blocks every request!
+    next();
+  }
+}
+
+// GOOD: Keep middleware lightweight
+
+// BAD: Not calling next()
+use(req: Request, res: Response, next: NextFunction) {
+  if (someCondition) {
+    return; // Request hangs!
+  }
+  next();
+}
+
+// GOOD: Always call next() or send response
+use(req: Request, res: Response, next: NextFunction) {
+  if (someCondition) {
+    res.status(400).json({ error: 'Bad request' });
+    return;
+  }
+  next();
+}
+
+// BAD: Modifying response after next()
+async use(req: Request, res: Response, next: NextFunction) {
+  next();
+  res.setHeader('X-Custom', 'value'); // May not work!
+}
+
+// GOOD: Modify before next() or use interceptor
+use(req: Request, res: Response, next: NextFunction) {
+  res.setHeader('X-Custom', 'value');
+  next();
+}
+
+// BAD: Using middleware for auth when guards exist
+// Middleware can't access ExecutionContext
+
+// GOOD: Use guards for authorization
+@UseGuards(AuthGuard)
+```

package/configs/nestjs/{.claude/rules → rules}/modules.md

@@ -3,10 +3,36 @@ paths:
   - "src/**/*.module.ts"
   - "src/**/*.controller.ts"
   - "src/**/*.service.ts"
+  - "src/main.ts"
 ---
 
 # NestJS Module Architecture
 
+## Global Configuration (main.ts)
+
+### ValidationPipe Setup
+
+```typescript
+import { ValidationPipe } from '@nestjs/common';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  app.useGlobalPipes(
+    new ValidationPipe({
+      whitelist: true,           // Strip non-whitelisted properties
+      forbidNonWhitelisted: true, // Throw error on extra properties
+      transform: true,            // Auto-transform payloads to DTO types
+      transformOptions: {
+        enableImplicitConversion: true,
+      },
+    }),
+  );
+
+  await app.listen(3000);
+}
+```
+
 ## Module Design
 
 ### Single Responsibility

package/configs/nestjs/rules/pipes.md

@@ -0,0 +1,351 @@
+---
+paths:
+  - "**/*.pipe.ts"
+  - "**/pipes/**/*.ts"
+---
+
+# NestJS Pipes
+
+## Built-in Pipes
+
+```typescript
+import {
+  ValidationPipe,
+  ParseIntPipe,
+  ParseBoolPipe,
+  ParseArrayPipe,
+  ParseUUIDPipe,
+  ParseEnumPipe,
+  DefaultValuePipe,
+} from '@nestjs/common';
+
+@Controller('users')
+export class UsersController {
+  // ParseIntPipe
+  @Get(':id')
+  findOne(@Param('id', ParseIntPipe) id: number) {
+    return this.usersService.findOne(id);
+  }
+
+  // ParseUUIDPipe with version
+  @Get(':uuid')
+  findByUuid(@Param('uuid', new ParseUUIDPipe({ version: '4' })) uuid: string) {
+    return this.usersService.findByUuid(uuid);
+  }
+
+  // ParseEnumPipe
+  @Get()
+  findByStatus(
+    @Query('status', new ParseEnumPipe(UserStatus)) status: UserStatus,
+  ) {
+    return this.usersService.findByStatus(status);
+  }
+
+  // DefaultValuePipe
+  @Get()
+  findAll(
+    @Query('page', new DefaultValuePipe(1), ParseIntPipe) page: number,
+    @Query('limit', new DefaultValuePipe(10), ParseIntPipe) limit: number,
+  ) {
+    return this.usersService.findAll({ page, limit });
+  }
+
+  // ParseArrayPipe
+  @Get()
+  findByIds(
+    @Query('ids', new ParseArrayPipe({ items: Number, separator: ',' }))
+    ids: number[],
+  ) {
+    return this.usersService.findByIds(ids);
+  }
+}
+```
+
+## Global Validation Pipe
+
+```typescript
+// main.ts
+import { ValidationPipe } from '@nestjs/common';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  app.useGlobalPipes(
+    new ValidationPipe({
+      whitelist: true,              // Strip non-decorated properties
+      forbidNonWhitelisted: true,   // Throw on extra properties
+      transform: true,              // Transform payloads to DTO types
+      transformOptions: {
+        enableImplicitConversion: true,
+      },
+      exceptionFactory: (errors) => {
+        const messages = errors.map((error) => ({
+          field: error.property,
+          constraints: Object.values(error.constraints || {}),
+        }));
+        return new BadRequestException({ errors: messages });
+      },
+    }),
+  );
+
+  await app.listen(3000);
+}
+```
+
+## Custom Pipes
+
+### Transform Pipe
+
+```typescript
+// pipes/parse-date.pipe.ts
+import { PipeTransform, Injectable, BadRequestException } from '@nestjs/common';
+
+@Injectable()
+export class ParseDatePipe implements PipeTransform<string, Date> {
+  transform(value: string): Date {
+    const date = new Date(value);
+
+    if (isNaN(date.getTime())) {
+      throw new BadRequestException(`Invalid date format: ${value}`);
+    }
+
+    return date;
+  }
+}
+
+// Usage
+@Get()
+findByDate(@Query('date', ParseDatePipe) date: Date) {
+  return this.service.findByDate(date);
+}
+```
+
+### Validation Pipe with Schema
+
+```typescript
+// pipes/zod-validation.pipe.ts
+import { PipeTransform, BadRequestException } from '@nestjs/common';
+import { ZodSchema, ZodError } from 'zod';
+
+export class ZodValidationPipe implements PipeTransform {
+  constructor(private readonly schema: ZodSchema) {}
+
+  transform(value: unknown) {
+    try {
+      return this.schema.parse(value);
+    } catch (error) {
+      if (error instanceof ZodError) {
+        throw new BadRequestException({
+          message: 'Validation failed',
+          errors: error.errors.map((e) => ({
+            path: e.path.join('.'),
+            message: e.message,
+          })),
+        });
+      }
+      throw error;
+    }
+  }
+}
+
+// Usage
+const createUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(2),
+});
+
+@Post()
+create(@Body(new ZodValidationPipe(createUserSchema)) dto: CreateUserDto) {
+  return this.usersService.create(dto);
+}
+```
+
+### Async Pipe
+
+```typescript
+// pipes/user-exists.pipe.ts
+import {
+  PipeTransform,
+  Injectable,
+  NotFoundException,
+} from '@nestjs/common';
+import { UsersService } from '../users.service';
+
+@Injectable()
+export class UserExistsPipe implements PipeTransform<string, Promise<User>> {
+  constructor(private readonly usersService: UsersService) {}
+
+  async transform(id: string): Promise<User> {
+    const user = await this.usersService.findOne(id);
+
+    if (!user) {
+      throw new NotFoundException(`User with ID ${id} not found`);
+    }
+
+    return user;
+  }
+}
+
+// Usage - returns User directly, not ID
+@Get(':id')
+findOne(@Param('id', UserExistsPipe) user: User) {
+  return user;
+}
+```
+
+### Trim and Sanitize
+
+```typescript
+// pipes/trim.pipe.ts
+import { PipeTransform, Injectable } from '@nestjs/common';
+
+@Injectable()
+export class TrimPipe implements PipeTransform {
+  transform(value: unknown) {
+    if (typeof value === 'string') {
+      return value.trim();
+    }
+
+    if (typeof value === 'object' && value !== null) {
+      return this.trimObject(value);
+    }
+
+    return value;
+  }
+
+  private trimObject(obj: Record<string, unknown>): Record<string, unknown> {
+    const trimmed: Record<string, unknown> = {};
+
+    for (const [key, val] of Object.entries(obj)) {
+      trimmed[key] = typeof val === 'string' ? val.trim() : val;
+    }
+
+    return trimmed;
+  }
+}
+```
+
+### File Validation Pipe
+
+```typescript
+// pipes/file-validation.pipe.ts
+import { PipeTransform, Injectable, BadRequestException } from '@nestjs/common';
+
+interface FileValidationOptions {
+  maxSize: number;
+  allowedMimeTypes: string[];
+}
+
+@Injectable()
+export class FileValidationPipe implements PipeTransform {
+  constructor(private readonly options: FileValidationOptions) {}
+
+  transform(file: Express.Multer.File) {
+    if (!file) {
+      throw new BadRequestException('File is required');
+    }
+
+    if (file.size > this.options.maxSize) {
+      throw new BadRequestException(
+        `File size exceeds ${this.options.maxSize / 1024 / 1024}MB`,
+      );
+    }
+
+    if (!this.options.allowedMimeTypes.includes(file.mimetype)) {
+      throw new BadRequestException(
+        `File type ${file.mimetype} is not allowed`,
+      );
+    }
+
+    return file;
+  }
+}
+
+// Usage
+@Post('upload')
+@UseInterceptors(FileInterceptor('file'))
+upload(
+  @UploadedFile(
+    new FileValidationPipe({
+      maxSize: 5 * 1024 * 1024,
+      allowedMimeTypes: ['image/jpeg', 'image/png'],
+    }),
+  )
+  file: Express.Multer.File,
+) {
+  return this.uploadService.upload(file);
+}
+```
+
+## Pipe Binding Scopes
+
+```typescript
+// Parameter level
+@Get(':id')
+findOne(@Param('id', ParseIntPipe) id: number) {}
+
+// Method level
+@Post()
+@UsePipes(ValidationPipe)
+create(@Body() dto: CreateDto) {}
+
+// Controller level
+@Controller('users')
+@UsePipes(TrimPipe)
+export class UsersController {}
+
+// Global level (main.ts)
+app.useGlobalPipes(new ValidationPipe());
+
+// Global with DI
+@Module({
+  providers: [
+    {
+      provide: APP_PIPE,
+      useClass: ValidationPipe,
+    },
+  ],
+})
+export class AppModule {}
+```
+
+## Anti-patterns
+
+```typescript
+// BAD: Pipe with side effects
+@Injectable()
+export class LoggingPipe implements PipeTransform {
+  transform(value: unknown) {
+    console.log(value); // Use interceptor instead
+    this.analyticsService.track(value); // Side effect!
+    return value;
+  }
+}
+
+// GOOD: Pipes are for transformation/validation only
+
+// BAD: Heavy async operations in pipe
+@Injectable()
+export class HeavyPipe implements PipeTransform {
+  async transform(value: string) {
+    await this.externalApi.validate(value); // Too slow
+    return value;
+  }
+}
+
+// GOOD: Keep pipes lightweight, use guards for auth checks
+
+// BAD: Not handling validation errors properly
+transform(value: string) {
+  return new Date(value); // Crashes on invalid input
+}
+
+// GOOD: Proper error handling
+transform(value: string) {
+  const date = new Date(value);
+  if (isNaN(date.getTime())) {
+    throw new BadRequestException('Invalid date');
+  }
+  return date;
+}
+```