@punks/cli 0.1.16 → 1.0.0

package/dist/skills/frameworks/nestjs/nestjs-best-practices/rules/di-avoid-service-locator.md

@@ -0,0 +1,104 @@
+---
+title: Avoid Service Locator Anti-Pattern
+impact: HIGH
+impactDescription: Hides dependencies and breaks testability
+tags: dependency-injection, anti-patterns, testing
+---
+
+## Avoid Service Locator Anti-Pattern
+
+Avoid using `ModuleRef.get()` or global containers to resolve dependencies at runtime. This hides dependencies, makes code harder to test, and breaks the benefits of dependency injection. Use constructor injection instead.
+
+**Incorrect (service locator anti-pattern):**
+
+```typescript
+// Use ModuleRef to get dependencies dynamically
+@Injectable()
+export class OrdersService {
+  constructor(private moduleRef: ModuleRef) {}
+
+  async createOrder(dto: CreateOrderDto): Promise<Order> {
+    // Dependencies are hidden - not visible in constructor
+    const usersService = this.moduleRef.get(UsersService);
+    const inventoryService = this.moduleRef.get(InventoryService);
+    const paymentService = this.moduleRef.get(PaymentService);
+
+    const user = await usersService.findOne(dto.userId);
+    // ... rest of logic
+  }
+}
+
+// Global singleton container
+class ServiceContainer {
+  private static instance: ServiceContainer;
+  private services = new Map<string, any>();
+
+  static getInstance(): ServiceContainer {
+    if (!this.instance) {
+      this.instance = new ServiceContainer();
+    }
+    return this.instance;
+  }
+
+  get<T>(key: string): T {
+    return this.services.get(key);
+  }
+}
+```
+
+**Correct (constructor injection with explicit dependencies):**
+
+```typescript
+// Use constructor injection - dependencies are explicit
+@Injectable()
+export class OrdersService {
+  constructor(
+    private usersService: UsersService,
+    private inventoryService: InventoryService,
+    private paymentService: PaymentService,
+  ) {}
+
+  async createOrder(dto: CreateOrderDto): Promise<Order> {
+    const user = await this.usersService.findOne(dto.userId);
+    const inventory = await this.inventoryService.check(dto.items);
+    // Dependencies are clear and testable
+  }
+}
+
+// Easy to test with mocks
+describe('OrdersService', () => {
+  let service: OrdersService;
+
+  beforeEach(async () => {
+    const module = await Test.createTestingModule({
+      providers: [
+        OrdersService,
+        { provide: UsersService, useValue: mockUsersService },
+        { provide: InventoryService, useValue: mockInventoryService },
+        { provide: PaymentService, useValue: mockPaymentService },
+      ],
+    }).compile();
+
+    service = module.get(OrdersService);
+  });
+});
+
+// VALID: Factory pattern for dynamic instantiation
+@Injectable()
+export class HandlerFactory {
+  constructor(private moduleRef: ModuleRef) {}
+
+  getHandler(type: string): Handler {
+    switch (type) {
+      case 'email':
+        return this.moduleRef.get(EmailHandler);
+      case 'sms':
+        return this.moduleRef.get(SmsHandler);
+      default:
+        return this.moduleRef.get(DefaultHandler);
+    }
+  }
+}
+```
+
+Reference: [NestJS Module Reference](https://docs.nestjs.com/fundamentals/module-ref)

package/dist/skills/frameworks/nestjs/nestjs-best-practices/rules/di-interface-segregation.md

@@ -0,0 +1,165 @@
+---
+title: Apply Interface Segregation Principle
+impact: HIGH
+impactDescription: Reduces coupling and improves testability by 30-50%
+tags: dependency-injection, interfaces, solid, isp
+---
+
+## Apply Interface Segregation Principle
+
+Clients should not be forced to depend on interfaces they don't use. In NestJS, this means keeping interfaces small and focused on specific capabilities rather than creating "fat" interfaces that bundle unrelated methods. When a service only needs to send emails, it shouldn't depend on an interface that also includes SMS, push notifications, and logging. Split large interfaces into role-based ones.
+
+**Incorrect (fat interface forcing unused dependencies):**
+
+```typescript
+// Fat interface - forces all consumers to depend on everything
+interface NotificationService {
+  sendEmail(to: string, subject: string, body: string): Promise<void>;
+  sendSms(phone: string, message: string): Promise<void>;
+  sendPush(userId: string, notification: PushPayload): Promise<void>;
+  sendSlack(channel: string, message: string): Promise<void>;
+  logNotification(type: string, payload: any): Promise<void>;
+  getDeliveryStatus(id: string): Promise<DeliveryStatus>;
+  retryFailed(id: string): Promise<void>;
+  scheduleNotification(dto: ScheduleDto): Promise<string>;
+}
+
+// Consumer only needs email, but must mock everything for tests
+@Injectable()
+export class OrdersService {
+  constructor(
+    private notifications: NotificationService, // Depends on 8 methods, uses 1
+  ) {}
+
+  async confirmOrder(order: Order): Promise<void> {
+    await this.notifications.sendEmail(
+      order.customer.email,
+      'Order Confirmed',
+      `Your order ${order.id} has been confirmed.`,
+    );
+  }
+}
+
+// Testing is painful - must mock unused methods
+const mockNotificationService = {
+  sendEmail: jest.fn(),
+  sendSms: jest.fn(),           // Never used, but required
+  sendPush: jest.fn(),          // Never used, but required
+  sendSlack: jest.fn(),         // Never used, but required
+  logNotification: jest.fn(),   // Never used, but required
+  getDeliveryStatus: jest.fn(), // Never used, but required
+  retryFailed: jest.fn(),       // Never used, but required
+  scheduleNotification: jest.fn(), // Never used, but required
+};
+```
+
+**Correct (segregated interfaces by capability):**
+
+```typescript
+// Segregated interfaces - each focused on one capability
+interface EmailSender {
+  sendEmail(to: string, subject: string, body: string): Promise<void>;
+}
+
+interface SmsSender {
+  sendSms(phone: string, message: string): Promise<void>;
+}
+
+interface PushSender {
+  sendPush(userId: string, notification: PushPayload): Promise<void>;
+}
+
+interface NotificationLogger {
+  logNotification(type: string, payload: any): Promise<void>;
+}
+
+interface NotificationScheduler {
+  scheduleNotification(dto: ScheduleDto): Promise<string>;
+}
+
+// Implementation can implement multiple interfaces
+@Injectable()
+export class NotificationService implements EmailSender, SmsSender, PushSender {
+  async sendEmail(to: string, subject: string, body: string): Promise<void> {
+    // Email implementation
+  }
+
+  async sendSms(phone: string, message: string): Promise<void> {
+    // SMS implementation
+  }
+
+  async sendPush(userId: string, notification: PushPayload): Promise<void> {
+    // Push implementation
+  }
+}
+
+// Or separate implementations
+@Injectable()
+export class SendGridEmailService implements EmailSender {
+  async sendEmail(to: string, subject: string, body: string): Promise<void> {
+    // SendGrid-specific implementation
+  }
+}
+
+// Consumer depends only on what it needs
+@Injectable()
+export class OrdersService {
+  constructor(
+    @Inject(EMAIL_SENDER) private emailSender: EmailSender, // Minimal dependency
+  ) {}
+
+  async confirmOrder(order: Order): Promise<void> {
+    await this.emailSender.sendEmail(
+      order.customer.email,
+      'Order Confirmed',
+      `Your order ${order.id} has been confirmed.`,
+    );
+  }
+}
+
+// Testing is simple - only mock what's used
+const mockEmailSender: EmailSender = {
+  sendEmail: jest.fn(),
+};
+
+// Module registration with tokens
+export const EMAIL_SENDER = Symbol('EMAIL_SENDER');
+export const SMS_SENDER = Symbol('SMS_SENDER');
+
+@Module({
+  providers: [
+    { provide: EMAIL_SENDER, useClass: SendGridEmailService },
+    { provide: SMS_SENDER, useClass: TwilioSmsService },
+  ],
+  exports: [EMAIL_SENDER, SMS_SENDER],
+})
+export class NotificationModule {}
+```
+
+**Combining interfaces when needed:**
+
+```typescript
+// Sometimes a consumer legitimately needs multiple capabilities
+interface EmailAndSmsSender extends EmailSender, SmsSender {}
+
+// Or use intersection types
+type MultiChannelSender = EmailSender & SmsSender & PushSender;
+
+// Consumer that genuinely needs multiple channels
+@Injectable()
+export class AlertService {
+  constructor(
+    @Inject(MULTI_CHANNEL_SENDER)
+    private sender: EmailSender & SmsSender,
+  ) {}
+
+  async sendCriticalAlert(user: User, message: string): Promise<void> {
+    await Promise.all([
+      this.sender.sendEmail(user.email, 'Critical Alert', message),
+      this.sender.sendSms(user.phone, message),
+    ]);
+  }
+}
+```
+
+Reference: [Interface Segregation Principle](https://en.wikipedia.org/wiki/Interface_segregation_principle)

package/dist/skills/frameworks/nestjs/nestjs-best-practices/rules/di-liskov-substitution.md

@@ -0,0 +1,221 @@
+---
+title: Honor Liskov Substitution Principle
+impact: HIGH
+impactDescription: Ensures implementations are truly interchangeable without breaking callers
+tags: dependency-injection, inheritance, solid, lsp
+---
+
+## Honor Liskov Substitution Principle
+
+Subtypes must be substitutable for their base types without altering program correctness. In NestJS with dependency injection, this means any implementation of an interface or abstract class must honor the contract completely. A mock payment service used in tests must behave like a real payment service (return similar shapes, handle errors the same way). Violating LSP causes subtle bugs when swapping implementations.
+
+**Incorrect (implementation violates the contract):**
+
+```typescript
+// Base interface with clear contract
+interface PaymentGateway {
+  /**
+   * Charges the specified amount.
+   * @returns PaymentResult on success
+   * @throws PaymentFailedException on payment failure
+   */
+  charge(amount: number, currency: string): Promise<PaymentResult>;
+}
+
+// Production implementation - follows the contract
+@Injectable()
+export class StripeService implements PaymentGateway {
+  async charge(amount: number, currency: string): Promise<PaymentResult> {
+    const response = await this.stripe.charges.create({ amount, currency });
+    return { success: true, transactionId: response.id, amount };
+  }
+}
+
+// Mock that violates LSP - different behavior!
+@Injectable()
+export class MockPaymentService implements PaymentGateway {
+  async charge(amount: number, currency: string): Promise<PaymentResult> {
+    // VIOLATION 1: Throws for valid input (contract says return PaymentResult)
+    if (amount > 1000) {
+      throw new Error('Mock does not support large amounts');
+    }
+
+    // VIOLATION 2: Returns null instead of PaymentResult
+    if (currency !== 'USD') {
+      return null as any; // Real service would convert or reject properly
+    }
+
+    // VIOLATION 3: Missing required field
+    return { success: true } as PaymentResult; // Missing transactionId!
+  }
+}
+
+// Consumer trusts the contract
+@Injectable()
+export class OrdersService {
+  constructor(@Inject(PAYMENT_GATEWAY) private payment: PaymentGateway) {}
+
+  async checkout(order: Order): Promise<void> {
+    const result = await this.payment.charge(order.total, order.currency);
+    // These fail with MockPaymentService:
+    await this.saveTransaction(result.transactionId); // undefined!
+    await this.sendReceipt(result); // might be null!
+  }
+}
+```
+
+**Correct (implementations honor the contract):**
+
+```typescript
+// Well-defined interface with documented behavior
+interface PaymentGateway {
+  /**
+   * Charges the specified amount.
+   * @param amount - Amount in smallest currency unit (cents)
+   * @param currency - ISO 4217 currency code
+   * @returns PaymentResult with transactionId, success status, and amount
+   * @throws PaymentFailedException if charge is declined
+   * @throws InvalidCurrencyException if currency is not supported
+   */
+  charge(amount: number, currency: string): Promise<PaymentResult>;
+
+  /**
+   * Refunds a previous charge.
+   * @throws TransactionNotFoundException if transactionId is invalid
+   */
+  refund(transactionId: string, amount?: number): Promise<RefundResult>;
+}
+
+// Production implementation
+@Injectable()
+export class StripeService implements PaymentGateway {
+  async charge(amount: number, currency: string): Promise<PaymentResult> {
+    try {
+      const response = await this.stripe.charges.create({ amount, currency });
+      return {
+        success: true,
+        transactionId: response.id,
+        amount: response.amount,
+      };
+    } catch (error) {
+      if (error.type === 'card_error') {
+        throw new PaymentFailedException(error.message);
+      }
+      throw error;
+    }
+  }
+
+  async refund(transactionId: string, amount?: number): Promise<RefundResult> {
+    // Implementation...
+  }
+}
+
+// Mock that honors LSP - same contract, same behavior shape
+@Injectable()
+export class MockPaymentService implements PaymentGateway {
+  private transactions = new Map<string, PaymentResult>();
+
+  async charge(amount: number, currency: string): Promise<PaymentResult> {
+    // Honor the contract: validate currency like real service would
+    if (!['USD', 'EUR', 'GBP'].includes(currency)) {
+      throw new InvalidCurrencyException(`Unsupported currency: ${currency}`);
+    }
+
+    // Simulate decline for specific test scenarios
+    if (amount === 99999) {
+      throw new PaymentFailedException('Card declined (test scenario)');
+    }
+
+    // Return same shape as production
+    const result: PaymentResult = {
+      success: true,
+      transactionId: `mock_${Date.now()}_${Math.random().toString(36)}`,
+      amount,
+    };
+
+    this.transactions.set(result.transactionId, result);
+    return result;
+  }
+
+  async refund(transactionId: string, amount?: number): Promise<RefundResult> {
+    // Honor the contract: throw if transaction not found
+    if (!this.transactions.has(transactionId)) {
+      throw new TransactionNotFoundException(transactionId);
+    }
+
+    return {
+      success: true,
+      refundId: `refund_${transactionId}`,
+      amount: amount ?? this.transactions.get(transactionId)!.amount,
+    };
+  }
+}
+
+// Consumer can swap implementations safely
+@Injectable()
+export class OrdersService {
+  constructor(@Inject(PAYMENT_GATEWAY) private payment: PaymentGateway) {}
+
+  async checkout(order: Order): Promise<Order> {
+    try {
+      const result = await this.payment.charge(order.total, order.currency);
+      // Works with both StripeService and MockPaymentService
+      order.transactionId = result.transactionId;
+      order.status = 'paid';
+      return order;
+    } catch (error) {
+      if (error instanceof PaymentFailedException) {
+        order.status = 'payment_failed';
+        return order;
+      }
+      throw error;
+    }
+  }
+}
+```
+
+**Testing LSP compliance:**
+
+```typescript
+// Shared test suite that any implementation must pass
+function testPaymentGatewayContract(
+  createGateway: () => PaymentGateway,
+) {
+  describe('PaymentGateway contract', () => {
+    let gateway: PaymentGateway;
+
+    beforeEach(() => {
+      gateway = createGateway();
+    });
+
+    it('returns PaymentResult with all required fields', async () => {
+      const result = await gateway.charge(1000, 'USD');
+      expect(result).toHaveProperty('success');
+      expect(result).toHaveProperty('transactionId');
+      expect(result).toHaveProperty('amount');
+      expect(typeof result.transactionId).toBe('string');
+    });
+
+    it('throws InvalidCurrencyException for unsupported currency', async () => {
+      await expect(gateway.charge(1000, 'INVALID'))
+        .rejects.toThrow(InvalidCurrencyException);
+    });
+
+    it('throws TransactionNotFoundException for invalid refund', async () => {
+      await expect(gateway.refund('nonexistent'))
+        .rejects.toThrow(TransactionNotFoundException);
+    });
+  });
+}
+
+// Run against all implementations
+describe('StripeService', () => {
+  testPaymentGatewayContract(() => new StripeService(mockStripeClient));
+});
+
+describe('MockPaymentService', () => {
+  testPaymentGatewayContract(() => new MockPaymentService());
+});
+```
+
+Reference: [Liskov Substitution Principle](https://en.wikipedia.org/wiki/Liskov_substitution_principle)

package/dist/skills/frameworks/nestjs/nestjs-best-practices/rules/di-prefer-constructor-injection.md

@@ -0,0 +1,86 @@
+---
+title: Prefer Constructor Injection
+impact: CRITICAL
+impactDescription: Required for proper DI and testing
+tags: dependency-injection, constructor, testing
+---
+
+## Prefer Constructor Injection
+
+Always use constructor injection over property injection. Constructor injection makes dependencies explicit, enables TypeScript type checking, ensures dependencies are available when the class is instantiated, and improves testability. This is required for proper DI, testing, and TypeScript support.
+
+**Incorrect (property injection with hidden dependencies):**
+
+```typescript
+// Property injection - avoid unless necessary
+@Injectable()
+export class UsersService {
+  @Inject()
+  private userRepo: UserRepository; // Hidden dependency
+
+  @Inject('CONFIG')
+  private config: ConfigType; // Also hidden
+
+  async findAll() {
+    return this.userRepo.find();
+  }
+}
+
+// Problems:
+// 1. Dependencies not visible in constructor
+// 2. Service can be instantiated without dependencies in tests
+// 3. TypeScript can't enforce dependency types at instantiation
+```
+
+**Correct (constructor injection with explicit dependencies):**
+
+```typescript
+// Constructor injection - explicit and testable
+@Injectable()
+export class UsersService {
+  constructor(
+    private readonly userRepo: UserRepository,
+    @Inject('CONFIG') private readonly config: ConfigType,
+  ) {}
+
+  async findAll(): Promise<User[]> {
+    return this.userRepo.find();
+  }
+}
+
+// Testing is straightforward
+describe('UsersService', () => {
+  let service: UsersService;
+  let mockRepo: jest.Mocked<UserRepository>;
+
+  beforeEach(() => {
+    mockRepo = {
+      find: jest.fn(),
+      save: jest.fn(),
+    } as any;
+
+    service = new UsersService(mockRepo, { dbUrl: 'test' });
+  });
+
+  it('should find all users', async () => {
+    mockRepo.find.mockResolvedValue([{ id: '1', name: 'Test' }]);
+    const result = await service.findAll();
+    expect(result).toHaveLength(1);
+  });
+});
+
+// Only use property injection for optional dependencies
+@Injectable()
+export class LoggingService {
+  @Optional()
+  @Inject('ANALYTICS')
+  private analytics?: AnalyticsService;
+
+  log(message: string) {
+    console.log(message);
+    this.analytics?.track('log', message); // Optional enhancement
+  }
+}
+```
+
+Reference: [NestJS Providers](https://docs.nestjs.com/providers)

package/dist/skills/frameworks/nestjs/nestjs-best-practices/rules/di-scope-awareness.md

@@ -0,0 +1,94 @@
+---
+title: Understand Provider Scopes
+impact: CRITICAL
+impactDescription: Prevents data leaks and performance issues
+tags: dependency-injection, scopes, request-context
+---
+
+## Understand Provider Scopes
+
+NestJS has three provider scopes: DEFAULT (singleton), REQUEST (per-request instance), and TRANSIENT (new instance for each injection). Most providers should be singletons. Request-scoped providers have performance implications as they bubble up through the dependency tree. Understanding scopes prevents memory leaks and incorrect data sharing.
+
+**Incorrect (wrong scope usage):**
+
+```typescript
+// Request-scoped when not needed (performance hit)
+@Injectable({ scope: Scope.REQUEST })
+export class UsersService {
+  // This creates a new instance for EVERY request
+  // All dependencies also become request-scoped
+  async findAll() {
+    return this.userRepo.find();
+  }
+}
+
+// Singleton with mutable request state
+@Injectable() // Default: singleton
+export class RequestContextService {
+  private userId: string; // DANGER: Shared across all requests!
+
+  setUser(userId: string) {
+    this.userId = userId; // Overwrites for all concurrent requests
+  }
+
+  getUser() {
+    return this.userId; // Returns wrong user!
+  }
+}
+```
+
+**Correct (appropriate scope for each use case):**
+
+```typescript
+// Singleton for stateless services (default, most common)
+@Injectable()
+export class UsersService {
+  constructor(private readonly userRepo: UserRepository) {}
+
+  async findById(id: string): Promise<User> {
+    return this.userRepo.findOne({ where: { id } });
+  }
+}
+
+// Request-scoped ONLY when you need request context
+@Injectable({ scope: Scope.REQUEST })
+export class RequestContextService {
+  private userId: string;
+
+  setUser(userId: string) {
+    this.userId = userId;
+  }
+
+  getUser(): string {
+    return this.userId;
+  }
+}
+
+// Better: Use NestJS built-in request context
+import { REQUEST } from '@nestjs/core';
+import { Request } from 'express';
+
+@Injectable({ scope: Scope.REQUEST })
+export class AuditService {
+  constructor(@Inject(REQUEST) private request: Request) {}
+
+  log(action: string) {
+    console.log(`User ${this.request.user?.id} performed ${action}`);
+  }
+}
+
+// Best: Use ClsModule for async context (no scope bubble-up)
+import { ClsService } from 'nestjs-cls';
+
+@Injectable() // Stays singleton!
+export class AuditService {
+  constructor(private cls: ClsService) {}
+
+  log(action: string) {
+    const userId = this.cls.get('userId');
+    console.log(`User ${userId} performed ${action}`);
+  }
+}
+```
+
+Reference: [NestJS Injection Scopes](https://docs.nestjs.com/fundamentals/injection-scopes)