@punks/cli 0.1.16 → 1.0.0

package/dist/skills/frameworks/nestjs/nestjs-best-practices/rules/arch-use-repository-pattern.md

@@ -0,0 +1,97 @@
+---
+title: Use Repository Pattern for Data Access
+impact: HIGH
+impactDescription: Decouples business logic from database
+tags: architecture, repository, data-access
+---
+
+## Use Repository Pattern for Data Access
+
+Create custom repositories to encapsulate complex queries and database logic. This keeps services focused on business logic, makes testing easier with mock repositories, and allows changing database implementations without affecting business code.
+
+**Incorrect (complex queries in services):**
+
+```typescript
+// Complex queries in services
+@Injectable()
+export class UsersService {
+  constructor(
+    @InjectRepository(User) private repo: Repository<User>,
+  ) {}
+
+  async findActiveWithOrders(minOrders: number): Promise<User[]> {
+    // Complex query logic mixed with business logic
+    return this.repo
+      .createQueryBuilder('user')
+      .leftJoinAndSelect('user.orders', 'order')
+      .where('user.isActive = :active', { active: true })
+      .andWhere('user.deletedAt IS NULL')
+      .groupBy('user.id')
+      .having('COUNT(order.id) >= :min', { min: minOrders })
+      .orderBy('user.createdAt', 'DESC')
+      .getMany();
+  }
+
+  // Service becomes bloated with query logic
+}
+```
+
+**Correct (custom repository with encapsulated queries):**
+
+```typescript
+// Custom repository with encapsulated queries
+@Injectable()
+export class UsersRepository {
+  constructor(
+    @InjectRepository(User) private repo: Repository<User>,
+  ) {}
+
+  async findById(id: string): Promise<User | null> {
+    return this.repo.findOne({ where: { id } });
+  }
+
+  async findByEmail(email: string): Promise<User | null> {
+    return this.repo.findOne({ where: { email } });
+  }
+
+  async findActiveWithMinOrders(minOrders: number): Promise<User[]> {
+    return this.repo
+      .createQueryBuilder('user')
+      .leftJoinAndSelect('user.orders', 'order')
+      .where('user.isActive = :active', { active: true })
+      .andWhere('user.deletedAt IS NULL')
+      .groupBy('user.id')
+      .having('COUNT(order.id) >= :min', { min: minOrders })
+      .orderBy('user.createdAt', 'DESC')
+      .getMany();
+  }
+
+  async save(user: User): Promise<User> {
+    return this.repo.save(user);
+  }
+}
+
+// Clean service with business logic only
+@Injectable()
+export class UsersService {
+  constructor(private usersRepo: UsersRepository) {}
+
+  async getActiveUsersWithOrders(): Promise<User[]> {
+    return this.usersRepo.findActiveWithMinOrders(1);
+  }
+
+  async create(dto: CreateUserDto): Promise<User> {
+    const existing = await this.usersRepo.findByEmail(dto.email);
+    if (existing) {
+      throw new ConflictException('Email already registered');
+    }
+
+    const user = new User();
+    user.email = dto.email;
+    user.name = dto.name;
+    return this.usersRepo.save(user);
+  }
+}
+```
+
+Reference: [Repository Pattern](https://martinfowler.com/eaaCatalog/repository.html)

package/dist/skills/frameworks/nestjs/nestjs-best-practices/rules/db-avoid-n-plus-one.md

@@ -0,0 +1,139 @@
+---
+title: Avoid N+1 Query Problems
+impact: HIGH
+impactDescription: N+1 queries are one of the most common performance killers
+tags: database, n-plus-one, queries, performance
+---
+
+## Avoid N+1 Query Problems
+
+N+1 queries occur when you fetch a list of entities, then make an additional query for each entity to load related data. Use eager loading with `relations`, query builder joins, or DataLoader to batch queries efficiently.
+
+**Incorrect (lazy loading in loops causes N+1):**
+
+```typescript
+// Lazy loading in loops causes N+1
+@Injectable()
+export class OrdersService {
+  async getOrdersWithItems(userId: string): Promise<Order[]> {
+    const orders = await this.orderRepo.find({ where: { userId } });
+    // 1 query for orders
+
+    for (const order of orders) {
+      // N additional queries - one per order!
+      order.items = await this.itemRepo.find({ where: { orderId: order.id } });
+    }
+
+    return orders;
+  }
+}
+
+// Accessing lazy relations without loading
+@Controller('users')
+export class UsersController {
+  @Get()
+  async findAll(): Promise<User[]> {
+    const users = await this.userRepo.find();
+    // If User.posts is lazy-loaded, serializing triggers N queries
+    return users; // Each user.posts access = 1 query
+  }
+}
+```
+
+**Correct (use relations for eager loading):**
+
+```typescript
+// Use relations option for eager loading
+@Injectable()
+export class OrdersService {
+  async getOrdersWithItems(userId: string): Promise<Order[]> {
+    // Single query with JOIN
+    return this.orderRepo.find({
+      where: { userId },
+      relations: ['items', 'items.product'],
+    });
+  }
+}
+
+// Use QueryBuilder for complex joins
+@Injectable()
+export class UsersService {
+  async getUsersWithPostCounts(): Promise<UserWithPostCount[]> {
+    return this.userRepo
+      .createQueryBuilder('user')
+      .leftJoin('user.posts', 'post')
+      .select('user.id', 'id')
+      .addSelect('user.name', 'name')
+      .addSelect('COUNT(post.id)', 'postCount')
+      .groupBy('user.id')
+      .getRawMany();
+  }
+
+  async getActiveUsersWithPosts(): Promise<User[]> {
+    return this.userRepo
+      .createQueryBuilder('user')
+      .leftJoinAndSelect('user.posts', 'post')
+      .leftJoinAndSelect('post.comments', 'comment')
+      .where('user.isActive = :active', { active: true })
+      .andWhere('post.status = :status', { status: 'published' })
+      .getMany();
+  }
+}
+
+// Use find options for specific fields
+async getOrderSummaries(userId: string): Promise<OrderSummary[]> {
+  return this.orderRepo.find({
+    where: { userId },
+    relations: ['items'],
+    select: {
+      id: true,
+      total: true,
+      status: true,
+      items: {
+        id: true,
+        quantity: true,
+        price: true,
+      },
+    },
+  });
+}
+
+// Use DataLoader for GraphQL to batch and cache queries
+import DataLoader from 'dataloader';
+
+@Injectable({ scope: Scope.REQUEST })
+export class PostsLoader {
+  constructor(private postsService: PostsService) {}
+
+  readonly batchPosts = new DataLoader<string, Post[]>(async (userIds) => {
+    // Single query for all users' posts
+    const posts = await this.postsService.findByUserIds([...userIds]);
+
+    // Group by userId
+    const postsMap = new Map<string, Post[]>();
+    for (const post of posts) {
+      const userPosts = postsMap.get(post.userId) || [];
+      userPosts.push(post);
+      postsMap.set(post.userId, userPosts);
+    }
+
+    // Return in same order as input
+    return userIds.map((id) => postsMap.get(id) || []);
+  });
+}
+
+// In resolver
+@ResolveField()
+async posts(@Parent() user: User): Promise<Post[]> {
+  // DataLoader batches multiple calls into single query
+  return this.postsLoader.batchPosts.load(user.id);
+}
+
+// Enable query logging in development to detect N+1
+TypeOrmModule.forRoot({
+  logging: ['query', 'error'],
+  logger: 'advanced-console',
+});
+```
+
+Reference: [TypeORM Relations](https://typeorm.io/relations)

package/dist/skills/frameworks/nestjs/nestjs-best-practices/rules/db-use-migrations.md

@@ -0,0 +1,129 @@
+---
+title: Use Database Migrations
+impact: HIGH
+impactDescription: Enables safe, repeatable database schema changes
+tags: database, migrations, typeorm, schema
+---
+
+## Use Database Migrations
+
+Never use `synchronize: true` in production. Use migrations for all schema changes. Migrations provide version control for your database, enable safe rollbacks, and ensure consistency across all environments.
+
+**Incorrect (using synchronize or manual SQL):**
+
+```typescript
+// Use synchronize in production
+TypeOrmModule.forRoot({
+  type: 'postgres',
+  synchronize: true, // DANGEROUS in production!
+  // Can drop columns, tables, or data
+});
+
+// Manual SQL in production
+@Injectable()
+export class DatabaseService {
+  async addColumn(): Promise<void> {
+    await this.dataSource.query('ALTER TABLE users ADD COLUMN age INT');
+    // No version control, no rollback, inconsistent across envs
+  }
+}
+
+// Modify entities without migration
+@Entity()
+export class User {
+  @Column()
+  email: string;
+
+  @Column() // Added without migration
+  newField: string; // Will crash in production if synchronize is false
+}
+```
+
+**Correct (use migrations for all schema changes):**
+
+```typescript
+// Configure TypeORM for migrations
+// data-source.ts
+export const dataSource = new DataSource({
+  type: 'postgres',
+  host: process.env.DB_HOST,
+  port: parseInt(process.env.DB_PORT),
+  username: process.env.DB_USERNAME,
+  password: process.env.DB_PASSWORD,
+  database: process.env.DB_NAME,
+  entities: ['dist/**/*.entity.js'],
+  migrations: ['dist/migrations/*.js'],
+  synchronize: false, // Always false in production
+  migrationsRun: true, // Run migrations on startup
+});
+
+// app.module.ts
+TypeOrmModule.forRootAsync({
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    type: 'postgres',
+    host: config.get('DB_HOST'),
+    synchronize: config.get('NODE_ENV') === 'development', // Only in dev
+    migrations: ['dist/migrations/*.js'],
+    migrationsRun: true,
+  }),
+});
+
+// migrations/1705312800000-AddUserAge.ts
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class AddUserAge1705312800000 implements MigrationInterface {
+  name = 'AddUserAge1705312800000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    // Add column with default to handle existing rows
+    await queryRunner.query(`
+      ALTER TABLE "users" ADD "age" integer DEFAULT 0
+    `);
+
+    // Add index for frequently queried columns
+    await queryRunner.query(`
+      CREATE INDEX "IDX_users_age" ON "users" ("age")
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    // Always implement down for rollback
+    await queryRunner.query(`DROP INDEX "IDX_users_age"`);
+    await queryRunner.query(`ALTER TABLE "users" DROP COLUMN "age"`);
+  }
+}
+
+// Safe column rename (two-step)
+export class RenameNameToFullName1705312900000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    // Step 1: Add new column
+    await queryRunner.query(`
+      ALTER TABLE "users" ADD "full_name" varchar(255)
+    `);
+
+    // Step 2: Copy data
+    await queryRunner.query(`
+      UPDATE "users" SET "full_name" = "name"
+    `);
+
+    // Step 3: Add NOT NULL constraint
+    await queryRunner.query(`
+      ALTER TABLE "users" ALTER COLUMN "full_name" SET NOT NULL
+    `);
+
+    // Step 4: Drop old column (after verifying app works)
+    await queryRunner.query(`
+      ALTER TABLE "users" DROP COLUMN "name"
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`ALTER TABLE "users" ADD "name" varchar(255)`);
+    await queryRunner.query(`UPDATE "users" SET "name" = "full_name"`);
+    await queryRunner.query(`ALTER TABLE "users" DROP COLUMN "full_name"`);
+  }
+}
+```
+
+Reference: [TypeORM Migrations](https://typeorm.io/migrations)

package/dist/skills/frameworks/nestjs/nestjs-best-practices/rules/db-use-transactions.md

@@ -0,0 +1,140 @@
+---
+title: Use Transactions for Multi-Step Operations
+impact: HIGH
+impactDescription: Ensures data consistency in multi-step operations
+tags: database, transactions, typeorm, consistency
+---
+
+## Use Transactions for Multi-Step Operations
+
+When multiple database operations must succeed or fail together, wrap them in a transaction. This prevents partial updates that leave your data in an inconsistent state. Use TypeORM's transaction APIs or the DataSource query runner for complex scenarios.
+
+**Incorrect (multiple saves without transaction):**
+
+```typescript
+// Multiple saves without transaction
+@Injectable()
+export class OrdersService {
+  async createOrder(userId: string, items: OrderItem[]): Promise<Order> {
+    // If any step fails, data is inconsistent
+    const order = await this.orderRepo.save({ userId, status: 'pending' });
+
+    for (const item of items) {
+      await this.orderItemRepo.save({ orderId: order.id, ...item });
+      await this.inventoryRepo.decrement({ productId: item.productId }, 'stock', item.quantity);
+    }
+
+    await this.paymentService.charge(order.id);
+    // If payment fails, order and inventory are already modified!
+
+    return order;
+  }
+}
+```
+
+**Correct (use DataSource.transaction for automatic rollback):**
+
+```typescript
+// Use DataSource.transaction() for automatic rollback
+@Injectable()
+export class OrdersService {
+  constructor(private dataSource: DataSource) {}
+
+  async createOrder(userId: string, items: OrderItem[]): Promise<Order> {
+    return this.dataSource.transaction(async (manager) => {
+      // All operations use the same transactional manager
+      const order = await manager.save(Order, { userId, status: 'pending' });
+
+      for (const item of items) {
+        await manager.save(OrderItem, { orderId: order.id, ...item });
+        await manager.decrement(
+          Inventory,
+          { productId: item.productId },
+          'stock',
+          item.quantity,
+        );
+      }
+
+      // If this throws, everything rolls back
+      await this.paymentService.chargeWithManager(manager, order.id);
+
+      return order;
+    });
+  }
+}
+
+// QueryRunner for manual transaction control
+@Injectable()
+export class TransferService {
+  constructor(private dataSource: DataSource) {}
+
+  async transfer(fromId: string, toId: string, amount: number): Promise<void> {
+    const queryRunner = this.dataSource.createQueryRunner();
+    await queryRunner.connect();
+    await queryRunner.startTransaction();
+
+    try {
+      // Debit source account
+      await queryRunner.manager.decrement(
+        Account,
+        { id: fromId },
+        'balance',
+        amount,
+      );
+
+      // Verify sufficient funds
+      const source = await queryRunner.manager.findOne(Account, {
+        where: { id: fromId },
+      });
+      if (source.balance < 0) {
+        throw new BadRequestException('Insufficient funds');
+      }
+
+      // Credit destination account
+      await queryRunner.manager.increment(
+        Account,
+        { id: toId },
+        'balance',
+        amount,
+      );
+
+      // Log the transaction
+      await queryRunner.manager.save(TransactionLog, {
+        fromId,
+        toId,
+        amount,
+        timestamp: new Date(),
+      });
+
+      await queryRunner.commitTransaction();
+    } catch (error) {
+      await queryRunner.rollbackTransaction();
+      throw error;
+    } finally {
+      await queryRunner.release();
+    }
+  }
+}
+
+// Repository method with transaction support
+@Injectable()
+export class UsersRepository {
+  constructor(
+    @InjectRepository(User) private repo: Repository<User>,
+    private dataSource: DataSource,
+  ) {}
+
+  async createWithProfile(
+    userData: CreateUserDto,
+    profileData: CreateProfileDto,
+  ): Promise<User> {
+    return this.dataSource.transaction(async (manager) => {
+      const user = await manager.save(User, userData);
+      await manager.save(Profile, { ...profileData, userId: user.id });
+      return user;
+    });
+  }
+}
+```
+
+Reference: [TypeORM Transactions](https://typeorm.io/transactions)