@punks/cli 0.1.16 → 1.0.0

package/dist/skills/frameworks/nestjs/nestjs-best-practices/rules/test-use-testing-module.md

@@ -0,0 +1,153 @@
+---
+title: Use Testing Module for Unit Tests
+impact: HIGH
+impactDescription: Enables proper isolated testing with mocked dependencies
+tags: testing, unit-tests, mocking, jest
+---
+
+## Use Testing Module for Unit Tests
+
+Use `@nestjs/testing` module to create isolated test environments with mocked dependencies. This ensures your tests run fast, don't depend on external services, and properly test your business logic in isolation.
+
+**Incorrect (manual instantiation bypassing DI):**
+
+```typescript
+// Instantiate services manually without DI
+describe('UsersService', () => {
+  it('should create user', async () => {
+    // Manual instantiation bypasses DI
+    const repo = new UserRepository(); // Real repo!
+    const service = new UsersService(repo);
+
+    const user = await service.create({ name: 'Test' });
+    // This hits the real database!
+  });
+});
+
+// Test implementation details
+describe('UsersController', () => {
+  it('should call service', async () => {
+    const service = { create: jest.fn() };
+    const controller = new UsersController(service as any);
+
+    await controller.create({ name: 'Test' });
+
+    expect(service.create).toHaveBeenCalled(); // Tests implementation, not behavior
+  });
+});
+```
+
+**Correct (use Test.createTestingModule with mocked dependencies):**
+
+```typescript
+// Use Test.createTestingModule for proper DI
+import { Test, TestingModule } from '@nestjs/testing';
+
+describe('UsersService', () => {
+  let service: UsersService;
+  let repo: jest.Mocked<UserRepository>;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        UsersService,
+        {
+          provide: UserRepository,
+          useValue: {
+            save: jest.fn(),
+            findOne: jest.fn(),
+            find: jest.fn(),
+          },
+        },
+      ],
+    }).compile();
+
+    service = module.get<UsersService>(UsersService);
+    repo = module.get(UserRepository);
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('create', () => {
+    it('should save and return user', async () => {
+      const dto = { name: 'John', email: 'john@test.com' };
+      const expectedUser = { id: '1', ...dto };
+
+      repo.save.mockResolvedValue(expectedUser);
+
+      const result = await service.create(dto);
+
+      expect(result).toEqual(expectedUser);
+      expect(repo.save).toHaveBeenCalledWith(dto);
+    });
+
+    it('should throw on duplicate email', async () => {
+      repo.findOne.mockResolvedValue({ id: '1', email: 'test@test.com' });
+
+      await expect(
+        service.create({ name: 'Test', email: 'test@test.com' }),
+      ).rejects.toThrow(ConflictException);
+    });
+  });
+
+  describe('findById', () => {
+    it('should return user when found', async () => {
+      const user = { id: '1', name: 'John' };
+      repo.findOne.mockResolvedValue(user);
+
+      const result = await service.findById('1');
+
+      expect(result).toEqual(user);
+    });
+
+    it('should throw NotFoundException when not found', async () => {
+      repo.findOne.mockResolvedValue(null);
+
+      await expect(service.findById('999')).rejects.toThrow(NotFoundException);
+    });
+  });
+});
+
+// Testing guards and interceptors
+describe('RolesGuard', () => {
+  let guard: RolesGuard;
+  let reflector: Reflector;
+
+  beforeEach(async () => {
+    const module = await Test.createTestingModule({
+      providers: [RolesGuard, Reflector],
+    }).compile();
+
+    guard = module.get<RolesGuard>(RolesGuard);
+    reflector = module.get<Reflector>(Reflector);
+  });
+
+  it('should allow when no roles required', () => {
+    const context = createMockExecutionContext({ user: { roles: [] } });
+    jest.spyOn(reflector, 'getAllAndOverride').mockReturnValue(undefined);
+
+    expect(guard.canActivate(context)).toBe(true);
+  });
+
+  it('should allow admin for admin-only route', () => {
+    const context = createMockExecutionContext({ user: { roles: ['admin'] } });
+    jest.spyOn(reflector, 'getAllAndOverride').mockReturnValue(['admin']);
+
+    expect(guard.canActivate(context)).toBe(true);
+  });
+});
+
+function createMockExecutionContext(request: Partial<Request>): ExecutionContext {
+  return {
+    switchToHttp: () => ({
+      getRequest: () => request,
+    }),
+    getHandler: () => jest.fn(),
+    getClass: () => jest.fn(),
+  } as ExecutionContext;
+}
+```
+
+Reference: [NestJS Testing](https://docs.nestjs.com/fundamentals/testing)

package/dist/skills/frameworks/nestjs/nestjs-best-practices/scripts/build-agents.ts

@@ -0,0 +1,299 @@
+#!/usr/bin/env npx ts-node
+
+/**
+ * Build script for generating AGENTS.md from individual rule files
+ *
+ * Usage: npx ts-node scripts/build-agents.ts
+ *
+ * This script:
+ * 1. Reads all rule files from the rules/ directory
+ * 2. Parses YAML frontmatter for metadata
+ * 3. Groups rules by category based on filename prefix
+ * 4. Generates a consolidated AGENTS.md file
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Category definitions with ordering and metadata
+const CATEGORIES = [
+  { prefix: 'arch-', name: 'Architecture', impact: 'CRITICAL', section: 1 },
+  { prefix: 'di-', name: 'Dependency Injection', impact: 'CRITICAL', section: 2 },
+  { prefix: 'error-', name: 'Error Handling', impact: 'HIGH', section: 3 },
+  { prefix: 'security-', name: 'Security', impact: 'HIGH', section: 4 },
+  { prefix: 'perf-', name: 'Performance', impact: 'HIGH', section: 5 },
+  { prefix: 'test-', name: 'Testing', impact: 'MEDIUM-HIGH', section: 6 },
+  { prefix: 'db-', name: 'Database & ORM', impact: 'MEDIUM-HIGH', section: 7 },
+  { prefix: 'api-', name: 'API Design', impact: 'MEDIUM', section: 8 },
+  { prefix: 'micro-', name: 'Microservices', impact: 'MEDIUM', section: 9 },
+  { prefix: 'devops-', name: 'DevOps & Deployment', impact: 'LOW-MEDIUM', section: 10 },
+];
+
+interface RuleFrontmatter {
+  title: string;
+  impact: string;
+  impactDescription: string;
+  tags: string[];
+}
+
+interface Rule {
+  filename: string;
+  frontmatter: RuleFrontmatter;
+  content: string;
+  category: string;
+  categorySection: number;
+}
+
+function parseFrontmatter(content: string): { frontmatter: RuleFrontmatter | null; body: string } {
+  const frontmatterRegex = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
+  const match = content.match(frontmatterRegex);
+
+  if (!match) {
+    return { frontmatter: null, body: content };
+  }
+
+  const frontmatterStr = match[1];
+  const body = match[2];
+
+  // Simple YAML parsing for our expected format
+  const frontmatter: Partial<RuleFrontmatter> = {};
+  const lines = frontmatterStr.split('\n');
+  let currentKey = '';
+  let inArray = false;
+  const arrayItems: string[] = [];
+
+  for (const line of lines) {
+    if (line.match(/^[a-zA-Z]+:/)) {
+      // Save previous array if we were collecting one
+      if (inArray && currentKey === 'tags') {
+        frontmatter.tags = arrayItems;
+      }
+      inArray = false;
+      arrayItems.length = 0;
+
+      const [key, ...valueParts] = line.split(':');
+      const value = valueParts.join(':').trim();
+      currentKey = key.trim();
+
+      if (value === '') {
+        // Might be start of array
+        inArray = true;
+      } else {
+        (frontmatter as any)[currentKey] = value;
+      }
+    } else if (inArray && line.trim().startsWith('-')) {
+      arrayItems.push(line.trim().replace(/^-\s*/, ''));
+    }
+  }
+
+  // Save final array if needed
+  if (inArray && currentKey === 'tags') {
+    frontmatter.tags = arrayItems;
+  }
+
+  return {
+    frontmatter: frontmatter as RuleFrontmatter,
+    body: body.trim()
+  };
+}
+
+function getCategoryForFile(filename: string): { name: string; section: number } | null {
+  for (const cat of CATEGORIES) {
+    if (filename.startsWith(cat.prefix)) {
+      return { name: cat.name, section: cat.section };
+    }
+  }
+  return null;
+}
+
+function readMetadata(): any {
+  const metadataPath = path.join(__dirname, '..', 'metadata.json');
+  return JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
+}
+
+function readRules(): Rule[] {
+  const rulesDir = path.join(__dirname, '..', 'rules');
+  const files = fs.readdirSync(rulesDir)
+    .filter(f => f.endsWith('.md') && !f.startsWith('_'));
+
+  const rules: Rule[] = [];
+
+  for (const file of files) {
+    const filePath = path.join(rulesDir, file);
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const { frontmatter, body } = parseFrontmatter(content);
+
+    if (!frontmatter) {
+      console.warn(`Warning: No frontmatter found in ${file}`);
+      continue;
+    }
+
+    const category = getCategoryForFile(file);
+    if (!category) {
+      console.warn(`Warning: Unknown category for ${file}`);
+      continue;
+    }
+
+    rules.push({
+      filename: file,
+      frontmatter,
+      content: body,
+      category: category.name,
+      categorySection: category.section
+    });
+  }
+
+  return rules;
+}
+
+function generateTableOfContents(rulesByCategory: Map<string, Rule[]>): string {
+  let toc = '## Table of Contents\n\n';
+
+  for (const cat of CATEGORIES) {
+    const rules = rulesByCategory.get(cat.name);
+    if (!rules || rules.length === 0) continue;
+
+    // Section anchor format: #1-architecture
+    const sectionAnchor = `${cat.section}-${cat.name.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`;
+    toc += `${cat.section}. [${cat.name}](#${sectionAnchor}) — **${cat.impact}**\n`;
+
+    for (let i = 0; i < rules.length; i++) {
+      const rule = rules[i];
+      // Rule anchor format: #11-rule-title
+      const ruleNum = `${cat.section}${i + 1}`;
+      const anchor = `${ruleNum}-${rule.frontmatter.title.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`;
+      toc += `   - ${cat.section}.${i + 1} [${rule.frontmatter.title}](#${anchor})\n`;
+    }
+  }
+
+  return toc;
+}
+
+function generateAgentsMd(rules: Rule[], metadata: any): string {
+  // Group rules by category
+  const rulesByCategory = new Map<string, Rule[]>();
+
+  for (const rule of rules) {
+    if (!rulesByCategory.has(rule.category)) {
+      rulesByCategory.set(rule.category, []);
+    }
+    rulesByCategory.get(rule.category)!.push(rule);
+  }
+
+  // Sort rules within each category alphabetically
+  for (const [category, categoryRules] of rulesByCategory) {
+    categoryRules.sort((a, b) => a.filename.localeCompare(b.filename));
+  }
+
+  // Build document
+  let doc = `# NestJS Best Practices
+
+**Version ${metadata.version}**
+${metadata.organization}
+${metadata.date}
+
+> **Note:**
+> This document is mainly for agents and LLMs to follow when maintaining,
+> generating, or refactoring NestJS codebases. Humans may also find it
+> useful, but guidance here is optimized for automation and consistency
+> by AI-assisted workflows.
+
+---
+
+## Abstract
+
+${metadata.abstract}
+
+---
+
+`;
+
+  // Add table of contents
+  doc += generateTableOfContents(rulesByCategory);
+  doc += '\n---\n\n';
+
+  // Add rules by category
+  for (const cat of CATEGORIES) {
+    const categoryRules = rulesByCategory.get(cat.name);
+    if (!categoryRules || categoryRules.length === 0) continue;
+
+    doc += `## ${cat.section}. ${cat.name}\n\n`;
+    doc += `**Section Impact: ${cat.impact}**\n\n`;
+
+    for (let i = 0; i < categoryRules.length; i++) {
+      const rule = categoryRules[i];
+      const ruleNumber = `${cat.section}.${i + 1}`;
+
+      // Add rule header with number (anchor will be auto-generated as #11-title)
+      doc += `### ${ruleNumber} ${rule.frontmatter.title}\n\n`;
+      doc += `**Impact: ${rule.frontmatter.impact}** — ${rule.frontmatter.impactDescription}\n\n`;
+
+      // Add rule content (skip the first header since we already added it)
+      let ruleContent = rule.content;
+      // Remove the first h1 or h2 header if it matches the title
+      ruleContent = ruleContent.replace(/^#{1,2}\s+.*\n+/, '');
+      // Remove the impact line if present (we already added it)
+      ruleContent = ruleContent.replace(/^\*\*Impact:.*\*\*.*\n+/, '');
+
+      doc += ruleContent;
+      doc += '\n\n---\n\n';
+    }
+  }
+
+  // Add references footer
+  doc += `## References
+
+`;
+  for (const ref of metadata.references) {
+    doc += `- ${ref}\n`;
+  }
+
+  doc += `
+---
+
+*Generated by build-agents.ts on ${new Date().toISOString().split('T')[0]}*
+`;
+
+  return doc;
+}
+
+function main() {
+  console.log('Building AGENTS.md...\n');
+
+  const metadata = readMetadata();
+  console.log(`Version: ${metadata.version}`);
+  console.log(`Organization: ${metadata.organization}\n`);
+
+  const rules = readRules();
+  console.log(`Found ${rules.length} rules\n`);
+
+  // Count by category
+  const counts = new Map<string, number>();
+  for (const rule of rules) {
+    counts.set(rule.category, (counts.get(rule.category) || 0) + 1);
+  }
+
+  console.log('Rules by category:');
+  for (const cat of CATEGORIES) {
+    const count = counts.get(cat.name) || 0;
+    if (count > 0) {
+      console.log(`  ${cat.name}: ${count}`);
+    }
+  }
+  console.log('');
+
+  const agentsMd = generateAgentsMd(rules, metadata);
+
+  const outputPath = path.join(__dirname, '..', 'AGENTS.md');
+  fs.writeFileSync(outputPath, agentsMd);
+
+  console.log(`Generated AGENTS.md (${agentsMd.length} bytes)`);
+  console.log(`Output: ${outputPath}`);
+}
+
+main();

package/dist/skills/frameworks/nestjs/nestjs-best-practices/scripts/build.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+
+# Build script for generating AGENTS.md
+# Usage: ./build.sh
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+# Check if ts-node is available
+if command -v npx &> /dev/null; then
+    echo "Running build with ts-node..."
+    npx ts-node build-agents.ts
+else
+    echo "Error: npx not found. Please install Node.js."
+    exit 1
+fi