opencode-andev-rules 1.0.0 → 1.0.2

package/skills/backend/nestJS/references/nestjs-testing.md

@@ -0,0 +1,395 @@
+# NestJS Testing Strategies
+
+## Test Types
+
+### Test Pyramid
+```
+    ╱╲
+   ╱ E2E ╲
+  ╱────────╲
+ ╱ Integration ╲
+╱────────────────╲
+╱   Unit Tests    ╲
+╱──────────────────╲
+```
+
+| Type | Speed | Scope | Confidence |
+|------|-------|-------|------------|
+| Unit | Fast | Single class/module | Low |
+| Integration | Medium | Module interactions | Medium |
+| E2E | Slow | Full system | High |
+
+## Unit Testing
+
+### Service Test
+```typescript
+import { Test } from '@nestjs/testing';
+import { UserService } from './user.service';
+import { UserRepository } from './user.repository';
+import { EmailService } from './email.service';
+
+describe('UserService', () => {
+  let service: UserService;
+  let userRepo: jest.Mocked<UserRepository>;
+  let emailService: jest.Mocked<EmailService>;
+
+  beforeEach(async () => {
+    const module = await Test.createTestingModule({
+      providers: [
+        UserService,
+        {
+          provide: UserRepository,
+          useValue: {
+            findById: jest.fn(),
+            save: jest.fn(),
+            delete: jest.fn(),
+          },
+        },
+        {
+          provide: EmailService,
+          useValue: {
+            sendWelcomeEmail: jest.fn(),
+          },
+        },
+      ],
+    }).compile();
+
+    service = module.get(UserService);
+    userRepo = module.get(UserRepository);
+    emailService = module.get(EmailService);
+  });
+
+  describe('createUser', () => {
+    it('should create a user and send welcome email', async () => {
+      const dto = { email: 'test@example.com', name: 'Test' };
+      const expectedUser = { id: '1', ...dto };
+
+      userRepo.save.mockResolvedValue(expectedUser);
+
+      const result = await service.createUser(dto);
+
+      expect(result).toEqual(expectedUser);
+      expect(userRepo.save).toHaveBeenCalledWith(expect.objectContaining(dto));
+      expect(emailService.sendWelcomeEmail).toHaveBeenCalledWith(expectedUser.id, dto.email);
+    });
+
+    it('should throw if email already exists', async () => {
+      userRepo.findByEmail.mockResolvedValue({ id: '1', email: 'exists@example.com' });
+
+      await expect(
+        service.createUser({ email: 'exists@example.com', name: 'Test' }),
+      ).rejects.toThrow('Email already exists');
+    });
+  });
+});
+```
+
+### Controller Test
+```typescript
+import { Test } from '@nestjs/testing';
+import { UserController } from './user.controller';
+import { UserService } from './user.service';
+
+describe('UserController', () => {
+  let controller: UserController;
+  let service: jest.Mocked<UserService>;
+
+  beforeEach(async () => {
+    const module = await Test.createTestingModule({
+      controllers: [UserController],
+      providers: [
+        {
+          provide: UserService,
+          useValue: {
+            createUser: jest.fn(),
+            findById: jest.fn(),
+            findAll: jest.fn(),
+          },
+        },
+      ],
+    }).compile();
+
+    controller = module.get(UserController);
+    service = module.get(UserService);
+  });
+
+  it('should return created user', async () => {
+    const dto = { email: 'test@example.com', name: 'Test' };
+    const expected = { id: '1', ...dto };
+
+    service.createUser.mockResolvedValue(expected);
+
+    const result = await controller.create(dto);
+
+    expect(result).toEqual(expected);
+    expect(result).not.toHaveProperty('password');
+  });
+});
+```
+
+## Integration Testing
+
+### Database Integration
+```typescript
+import { Test } from '@nestjs/testing';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { UserService } from './user.service';
+import { User } from './user.entity';
+import { UserModule } from './user.module';
+import { createTestDatabase } from '../test/utils/database';
+
+describe('UserService Integration', () => {
+  let service: UserService;
+  let module: TestingModule;
+
+  beforeAll(async () => {
+    const database = await createTestDatabase();
+
+    module = await Test.createTestingModule({
+      imports: [
+        TypeOrmModule.forRoot(database.config),
+        UserModule,
+      ],
+    }).compile();
+
+    service = module.get(UserService);
+  });
+
+  afterAll(async () => {
+    await module.close();
+  });
+
+  beforeEach(async () => {
+    await cleanDatabase();
+  });
+
+  it('should persist user to database', async () => {
+    const user = await service.createUser({
+      email: 'test@example.com',
+      name: 'Test User',
+    });
+
+    const found = await service.findById(user.id);
+    expect(found).toBeDefined();
+    expect(found.email).toBe('test@example.com');
+  });
+
+  it('should enforce unique email constraint', async () => {
+    await service.createUser({
+      email: 'dupe@example.com',
+      name: 'First',
+    });
+
+    await expect(
+      service.createUser({
+        email: 'dupe@example.com',
+        name: 'Second',
+      }),
+    ).rejects.toThrow();
+  });
+});
+```
+
+### HTTP Integration
+```typescript
+import * as request from 'supertest';
+import { Test } from '@nestjs/testing';
+import { INestApplication } from '@nestjs/common';
+import { AppModule } from '../src/app.module';
+
+describe('User API (integration)', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    const module = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    app = module.createNestApplication();
+    await app.init();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  describe('POST /users', () => {
+    it('should create user', async () => {
+      const response = await request(app.getHttpServer())
+        .post('/users')
+        .send({ email: 'test@example.com', name: 'Test' })
+        .expect(201);
+
+      expect(response.body).toHaveProperty('id');
+      expect(response.body.email).toBe('test@example.com');
+    });
+
+    it('should reject invalid email', async () => {
+      await request(app.getHttpServer())
+        .post('/users')
+        .send({ email: 'invalid', name: 'Test' })
+        .expect(400);
+    });
+  });
+});
+```
+
+## E2E Testing
+
+### Full E2E Test
+```typescript
+import * as request from 'supertest';
+import { Test } from '@nestjs/testing';
+import { INestApplication } from '@nestjs/common';
+import { AppModule } from '../src/app.module';
+
+describe('User E2E', () => {
+  let app: INestApplication;
+  let authToken: string;
+
+  beforeAll(async () => {
+    const module = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    app = module.createNestApplication();
+    await app.init();
+
+    // Auth
+    const loginRes = await request(app.getHttpServer())
+      .post('/auth/login')
+      .send({ email: 'admin@test.com', password: 'admin123' });
+
+    authToken = loginRes.body.accessToken;
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it('full user lifecycle', async () => {
+    // Create
+    const createRes = await request(app.getHttpServer())
+      .post('/users')
+      .set('Authorization', `Bearer ${authToken}`)
+      .send({ email: 'new@test.com', name: 'New User' })
+      .expect(201);
+
+    const userId = createRes.body.id;
+
+    // Read
+    await request(app.getHttpServer())
+      .get(`/users/${userId}`)
+      .set('Authorization', `Bearer ${authToken}`)
+      .expect(200);
+
+    // List
+    const listRes = await request(app.getHttpServer())
+      .get('/users')
+      .set('Authorization', `Bearer ${authToken}`)
+      .expect(200);
+
+    expect(listRes.body.data.length).toBeGreaterThan(0);
+
+    // Delete
+    await request(app.getHttpServer())
+      .delete(`/users/${userId}`)
+      .set('Authorization', `Bearer ${authToken}`)
+      .expect(204);
+  });
+});
+```
+
+## Test Database Utilities
+
+### Test Database Setup
+```typescript
+import { TypeOrmModuleOptions } from '@nestjs/typeorm';
+import { PostgreSqlContainer, StartedPostgreSqlContainer } from '@testcontainers/postgresql';
+
+export async function createTestDatabase(): Promise<{
+  container: StartedPostgreSqlContainer;
+  config: TypeOrmModuleOptions;
+}> {
+  const container = await new PostgreSqlContainer()
+    .withDatabase('test')
+    .withUsername('test')
+    .withPassword('test')
+    .start();
+
+  const config: TypeOrmModuleOptions = {
+    type: 'postgres',
+    host: container.getHost(),
+    port: container.getMappedPort(5432),
+    username: container.getUsername(),
+    password: container.getPassword(),
+    database: container.getDatabase(),
+    entities: ['dist/**/*.entity{.ts,.js}'],
+    synchronize: true,
+  };
+
+  return { container, config };
+}
+
+export async function cleanDatabase(): Promise<void> {
+  const entities = getMetadataArgsStorage().tables.map((t) => t.name);
+  for (const entity of entities) {
+    await getConnection().manager.query(`TRUNCATE TABLE "${entity}" CASCADE`);
+  }
+}
+```
+
+## Mocking Strategies
+
+### Service Mocking
+```typescript
+// Mock factory
+export const createMockUserService = (): jest.Mocked<UserService> => ({
+  createUser: jest.fn(),
+  findById: jest.fn(),
+  findAll: jest.fn(),
+  updateUser: jest.fn(),
+  deleteUser: jest.fn(),
+});
+
+// Custom provider
+const mockUserService = createMockUserService();
+mockUserService.findById.mockResolvedValue(testUser);
+
+const module = await Test.createTestingModule({
+  providers: [
+    { provide: UserService, useValue: mockUserService },
+  ],
+}).compile();
+```
+
+### Guard Mocking
+```typescript
+import { ExecutionContext } from '@nestjs/common';
+
+export const mockAuthGuard = {
+  canActivate: jest.fn((context: ExecutionContext) => {
+    const req = context.switchToHttp().getRequest();
+    req.user = { id: 'test-user-id', roles: ['admin'] };
+    return true;
+  }),
+};
+
+// Override guard in test
+const module = await Test.createTestingModule({
+  imports: [UserModule],
+})
+  .overrideGuard(AuthGuard('jwt'))
+  .useValue(mockAuthGuard)
+  .compile();
+```
+
+## Key Points
+- Unit tests mock all dependencies and test single classes in isolation
+- Integration tests use real database (TestContainers) and verify module interactions
+- E2E tests exercise the full HTTP stack including guards, pipes, interceptors
+- TestContainers provides disposable databases for integration testing
+- Clean database between tests to avoid state pollution
+- Guard mocking enables testing authenticated endpoints without tokens
+- Service mocking with jest.Mocked<T> provides type-safe mocks
+- Override providers and guards for controlled test scenarios

package/skills/infrastructure/prisma/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: prisma
+description: Prisma ORM rules — client setup, queries, errors, transactions, migrations. Use when building or reviewing Prisma data access.
+---
+
+# Prisma Skill
+
+## Setup
+
+- One PrismaClient singleton for the whole app — never `new PrismaClient()` per request or per service.
+- Provide it once (global module / DI) — services inject it, never instantiate it.
+- Datasource URL from env only — never hardcode connection strings, never log them.
+- Size the pool via `connection_limit`/`pool_timeout` — serverless or hot-reload dev must reuse the singleton or use an external pooler.
+
+## Relations: FK/PK decision
+
+- Always ask the user before modeling relations: database-enforced foreign keys vs Prisma-emulated relations (`relationMode = "prisma"`).
+- Without DB-level FKs, Prisma can still join via `include` — but nothing enforces referential integrity in the database.
+- With DB FKs: integrity enforced by the database; `onDelete` acts at the DB level; migrations carry the constraints.
+- Without DB FKs: integrity must be enforced in application code (existence checks + transactions); no `onDelete` in the database; fits providers without FK support.
+- Never assume one mode — the choice changes schema, migrations, and error handling; confirm it first.
+
+## Queries
+
+- Use `select` when only a subset of fields is required — don't over-fetch.
+- Avoid N+1 queries — use `include` or joins, not loops.
+- Avoid `include` for large relation collections — paginate or `select` instead.
+- Prisma fetches all scalar columns by default — with wide tables or heavy columns (text, JSON), always narrow it down.
+- Never blanket `include` — it pulls every column of the related table; nest `select` inside instead.
+
+```typescript
+// Good — narrow scalars, nested select for relations
+await prisma.user.findMany({
+  select: { id: true, name: true, posts: { select: { id: true, title: true } } },
+});
+
+// Or drop heavy fields (Prisma 6.2+)
+await prisma.post.findMany({ omit: { content: true } });
+```
+- Use `findUnique` when the field is unique — `findFirst` only otherwise.
+- Paginate `findMany` — never return unbounded results; cursor pagination for large datasets, offset for small.
+- Always `orderBy` deterministic fields for pagination.
+- Run independent queries in parallel — don't `await` sequentially.
+- Never raw SQL unless performance-critical (comment why) — never concatenate values into queries, use parameterized inputs.
+
+## Errors
+
+- Map Prisma errors to domain exceptions in one place (`P2002` → conflict, `P2025` → not found, ...) — never leak raw Prisma errors to API responses.
+
+## Transactions
+
+- Multi-step writes go in `$transaction` — no partial writes.
+- Keep transaction scope small — no external calls inside transactions.
+- Race conditions on read-modify-write — use transactions or locks.
+
+## Migrations
+
+- Keep migrations in `prisma/migrations` and commit them — never edit an applied migration, create a new one instead.
+- Deploy with `migrate deploy` — never `migrate dev` against prod.
+- Review destructive changes (drop column/table, type narrowing) before applying — backfill via a data migration when rows exist.
+
+## References
+
+- Schema layout, models, indexes, relations, enums: `references/prisma-schema.md`.
+- CLI, CRUD, optimization catalog: `references/prisma-queries.md`.

package/skills/infrastructure/prisma/references/prisma-queries.md

@@ -0,0 +1,197 @@
+# Prisma Queries & Operations
+
+Samples assume the global singleton `prisma` (see `SKILL.md` Setup) — never `new PrismaClient()` per call.
+
+## CLI
+
+| Command | Use |
+|---|---|
+| `prisma generate` | Regenerate Prisma Client |
+| `prisma migrate dev` | Create and apply migrations in dev |
+| `prisma migrate deploy` | Apply migrations in production/CI |
+| `prisma db push` | Push schema straight to DB, no migration (prototypes only) |
+| `prisma db pull` | Introspect an existing DB into the schema |
+| `prisma studio` | Open the GUI |
+
+## CRUD
+
+```typescript
+// Create
+await prisma.user.create({ data: { email: 'a@b.com', name: 'An' } });
+
+// Read
+await prisma.user.findUnique({ where: { email: 'a@b.com' } });
+await prisma.user.findMany({
+  where: { name: { contains: 'An' } },
+  orderBy: { id: 'desc' },
+  take: 10,
+});
+
+// Update / Delete
+await prisma.user.update({ where: { id: 'user_01' }, data: { name: 'Bình' } });
+await prisma.user.delete({ where: { id: 'user_01' } });
+
+// Relations — narrow, never blanket include
+await prisma.user.findMany({
+  select: { id: true, name: true, posts: { select: { id: true, title: true } } },
+});
+
+// Transaction (independent writes)
+await prisma.$transaction([
+  prisma.user.create({ data: { email: 'x@y.com', name: 'X' } }),
+  prisma.post.create({ data: { title: 'Hi', authorId: 'user_01' } }),
+]);
+```
+
+## Optimization
+
+### 1. Select only what you need (`select` / `omit`)
+
+- Same rule as `SKILL.md` Queries — full example there.
+- Never blanket `include` — it pulls every column of the related table.
+
+### 2. Avoid N+1 queries
+
+```typescript
+// Wrong (N+1)
+const users = await prisma.user.findMany();
+for (const u of users) {
+  u.posts = await prisma.post.findMany({ where: { authorId: u.id } });
+}
+
+// Right — one round trip, narrowed
+const users = await prisma.user.findMany({
+  select: { id: true, name: true, posts: { select: { id: true, title: true } } },
+});
+```
+
+- `relationLoadStrategy: 'join'` lets Prisma use one JOIN instead of separate queries — check preview/GA status for your Prisma version.
+- Simultaneous `findUnique` calls in the same tick are auto-batched (dataloader) — useful for GraphQL resolvers.
+
+### 3. Index the right columns
+
+```prisma
+model Post {
+  // ...
+  @@index([authorId])                 // FK
+  @@index([published, createdAt])     // composite for filter + sort
+  @@unique([authorId, slug])
+
+  @@map("posts")
+}
+```
+
+- Index columns used in `where`, `orderBy`, joins — column order matters in composite indexes.
+- Never over-index — indexes slow down writes.
+
+### 4. Paginate efficiently
+
+- Offset (`skip` + `take`) slows down as `skip` grows — the DB still scans skipped rows.
+- Cursor pagination is stable and fast for large datasets:
+
+```typescript
+await prisma.post.findMany({
+  take: 20,
+  skip: 1,
+  cursor: { id: lastId },
+  orderBy: { id: 'asc' },
+});
+```
+
+### 5. Batch writes
+
+- Never loop single-row writes — use batch operations:
+
+```typescript
+await prisma.user.createMany({ data: users, skipDuplicates: true });
+await prisma.post.updateMany({ where: { authorId: 'user_01' }, data: { published: true } });
+await prisma.post.deleteMany({ where: { published: false } });
+```
+
+### 6. Connection pooling
+
+- Reuse the singleton everywhere — hot-reload dev and serverless must guard it, never create clients per invocation:
+
+```typescript
+const globalForPrisma = globalThis as unknown as { prisma?: PrismaClient };
+export const prisma = globalForPrisma.prisma ?? new PrismaClient();
+if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;
+```
+
+- Size the pool via connection string: `?connection_limit=10&pool_timeout=20`.
+- Serverless (Vercel, Lambda): use an external pooler (PgBouncer, Supabase pooler, Prisma Accelerate) — never exhaust direct connections.
+
+### 7. Aggregate in the database
+
+```typescript
+await prisma.post.groupBy({ by: ['authorId'], _count: { _all: true } });
+await prisma.order.aggregate({ _sum: { total: true }, where: { status: 'PAID' } });
+await prisma.user.findMany({ include: { _count: { select: { posts: true } } } });
+```
+
+- Filter, sort, and count in the DB — never pull everything and `.filter()` in code.
+
+### 8. Keep transactions lean
+
+- `$transaction([...])` batch form for independent operations.
+- Interactive form only when logic runs between steps — keep it short:
+
+```typescript
+await prisma.$transaction(
+  async (tx) => {
+    const acc = await tx.account.update({
+      where: { id },
+      data: { balance: { decrement: 100 } },
+    });
+    if (acc.balance < 0) throw new Error('Insufficient balance');
+  },
+  { timeout: 5000, maxWait: 2000 },
+);
+```
+
+- No external API calls, no heavy work inside transactions — they hold connections and locks.
+
+### 9. Raw queries for complex cases
+
+- Window functions, CTEs, advanced full-text search: use raw queries.
+- Always the tagged template form — never string-concatenate user input:
+
+```typescript
+const rows = await prisma.$queryRaw`
+  SELECT author_id, COUNT(*) FROM "posts" WHERE published = true GROUP BY author_id
+`;
+```
+
+- Never `$queryRawUnsafe` with user input — use TypedSQL for typed raw queries.
+
+### 10. Measure before optimizing
+
+```typescript
+const prisma = new PrismaClient({ log: ['query', 'warn', 'error'] });
+```
+
+- Enable query logging in dev (on the singleton) to catch N+1 and redundant queries.
+- Run `EXPLAIN ANALYZE` on generated SQL to confirm index usage.
+- Trace per-query time with OpenTelemetry or Prisma `$extends`.
+
+### 11. Cache
+
+- Cache heavy-read, rarely-changed results with Redis or in-memory.
+- Prisma Accelerate supports `cacheStrategy: { ttl: 60, swr: 120 }`.
+
+### 12. Cold start / bundle
+
+- Edge/serverless: consider driver adapters (Neon, PlanetScale, D1, ...) to cut size and startup latency — check your Prisma version.
+- Generate only the needed binary targets on deploy (`binaryTargets`).
+
+## Checklist
+
+- One PrismaClient singleton
+- Always `select`/`omit` on wide tables
+- No queries in loops — use `include`, `in`, `createMany`
+- Indexes on FKs and filter/sort columns
+- Cursor pagination for large lists
+- Short transactions
+- Query logging in dev to catch N+1
+- Pooler for serverless
+- Raw SQL for complex queries (safe tagged-template form)