@aicgen/aicgen 1.0.0 → 1.0.2

package/.agent/rules/testing.md

@@ -1,572 +0,0 @@
-# Testing Rules
-
-# Unit Testing Fundamentals
-
-## Arrange-Act-Assert Pattern
-
-```typescript
-describe('UserService', () => {
-  it('should create user with hashed password', async () => {
-    // Arrange - Set up test data and dependencies
-    const userData = { email: 'test@example.com', password: 'secret123' };
-    const mockRepo = { save: jest.fn().mockResolvedValue({ id: '1', ...userData }) };
-    const service = new UserService(mockRepo);
-
-    // Act - Execute the behavior being tested
-    const result = await service.createUser(userData);
-
-    // Assert - Verify the outcomes
-    expect(result.id).toBe('1');
-    expect(mockRepo.save).toHaveBeenCalledWith(
-      expect.objectContaining({ email: 'test@example.com' })
-    );
-  });
-});
-```
-
-## Test Observable Behavior, Not Implementation
-
-```typescript
-// ❌ Bad: Testing implementation details
-it('should call validateEmail method', () => {
-  const spy = jest.spyOn(service, 'validateEmail');
-  service.createUser({ email: 'test@example.com' });
-  expect(spy).toHaveBeenCalled();
-});
-
-// ✅ Good: Testing observable behavior
-it('should reject invalid email', async () => {
-  await expect(
-    service.createUser({ email: 'invalid-email' })
-  ).rejects.toThrow('Invalid email format');
-});
-
-it('should accept valid email', async () => {
-  const result = await service.createUser({ email: 'valid@example.com' });
-  expect(result.email).toBe('valid@example.com');
-});
-```
-
-## One Assertion Per Test Concept
-
-```typescript
-// ❌ Bad: Multiple unrelated assertions
-it('should validate user input', () => {
-  expect(() => validate({ age: -1 })).toThrow();
-  expect(() => validate({ age: 200 })).toThrow();
-  expect(() => validate({ name: '' })).toThrow();
-});
-
-// ✅ Good: One test per scenario
-it('should reject negative age', () => {
-  expect(() => validate({ age: -1 })).toThrow('Age must be positive');
-});
-
-it('should reject age over 150', () => {
-  expect(() => validate({ age: 200 })).toThrow('Age must be under 150');
-});
-
-it('should reject empty name', () => {
-  expect(() => validate({ name: '' })).toThrow('Name is required');
-});
-```
-
-## Descriptive Test Names
-
-```typescript
-// ❌ Vague names
-it('should work correctly', () => {});
-it('handles edge case', () => {});
-
-// ✅ Descriptive names - describe the scenario and expected outcome
-it('should return empty array when no users match filter', () => {});
-it('should throw ValidationError when email is empty', () => {});
-it('should retry failed payment up to 3 times before giving up', () => {});
-```
-
-## Tests Should Be Independent
-
-```typescript
-// ❌ Bad: Tests depend on each other
-let userId: string;
-
-it('should create user', async () => {
-  const user = await service.createUser(data);
-  userId = user.id; // Shared state!
-});
-
-it('should update user', async () => {
-  await service.updateUser(userId, newData); // Depends on previous test
-});
-
-// ✅ Good: Each test is self-contained
-it('should update user', async () => {
-  const user = await service.createUser(data);
-  const updated = await service.updateUser(user.id, newData);
-  expect(updated.name).toBe(newData.name);
-});
-```
-
-## Test Edge Cases
-
-```typescript
-describe('divide', () => {
-  it('should divide two positive numbers', () => {
-    expect(divide(10, 2)).toBe(5);
-  });
-
-  it('should throw when dividing by zero', () => {
-    expect(() => divide(10, 0)).toThrow('Division by zero');
-  });
-
-  it('should handle negative numbers', () => {
-    expect(divide(-10, 2)).toBe(-5);
-  });
-
-  it('should return zero when numerator is zero', () => {
-    expect(divide(0, 5)).toBe(0);
-  });
-});
-```
-
-
----
-
-# Test Doubles and Mocking
-
-## Types of Test Doubles
-
-```typescript
-// STUB: Returns canned responses
-const stubUserRepo = {
-  findById: () => ({ id: '1', name: 'Test User' })
-};
-
-// MOCK: Pre-programmed with expectations
-const mockPaymentGateway = {
-  charge: jest.fn()
-    .mockResolvedValueOnce({ success: true, transactionId: 'tx1' })
-    .mockResolvedValueOnce({ success: false, error: 'Declined' })
-};
-
-// SPY: Records calls for verification
-const spy = jest.spyOn(emailService, 'send');
-
-// FAKE: Working implementation (not for production)
-class FakeDatabase implements Database {
-  private data = new Map<string, any>();
-
-  async save(id: string, entity: any) { this.data.set(id, entity); }
-  async find(id: string) { return this.data.get(id); }
-}
-```
-
-## When to Mock
-
-```typescript
-// ✅ Mock external services (APIs, databases)
-const mockHttpClient = {
-  get: jest.fn().mockResolvedValue({ data: userData })
-};
-
-// ✅ Mock time-dependent operations
-jest.useFakeTimers();
-jest.setSystemTime(new Date('2024-01-15'));
-
-// ✅ Mock random/non-deterministic functions
-jest.spyOn(Math, 'random').mockReturnValue(0.5);
-
-// ❌ Don't mock the code you're testing
-// ❌ Don't mock simple data structures
-```
-
-## Mock Verification
-
-```typescript
-it('should send welcome email after registration', async () => {
-  const mockEmail = { send: jest.fn().mockResolvedValue(true) };
-  const service = new UserService({ emailService: mockEmail });
-
-  await service.register({ email: 'new@example.com' });
-
-  expect(mockEmail.send).toHaveBeenCalledWith({
-    to: 'new@example.com',
-    template: 'welcome',
-    subject: 'Welcome!'
-  });
-  expect(mockEmail.send).toHaveBeenCalledTimes(1);
-});
-```
-
-## Partial Mocks
-
-```typescript
-// Mock only specific methods
-const service = new OrderService();
-
-jest.spyOn(service, 'validateOrder').mockReturnValue(true);
-jest.spyOn(service, 'calculateTotal').mockReturnValue(100);
-// Other methods use real implementation
-
-const result = await service.processOrder(orderData);
-expect(result.total).toBe(100);
-```
-
-## Resetting Mocks
-
-```typescript
-describe('PaymentService', () => {
-  const mockGateway = { charge: jest.fn() };
-  const service = new PaymentService(mockGateway);
-
-  beforeEach(() => {
-    jest.clearAllMocks(); // Clear call history
-    // or jest.resetAllMocks() to also reset return values
-  });
-
-  it('should process payment', async () => {
-    mockGateway.charge.mockResolvedValue({ success: true });
-    await service.charge(100);
-    expect(mockGateway.charge).toHaveBeenCalledTimes(1);
-  });
-});
-```
-
-## Mock Modules
-
-```typescript
-// Mock entire module
-jest.mock('./email-service', () => ({
-  EmailService: jest.fn().mockImplementation(() => ({
-    send: jest.fn().mockResolvedValue(true)
-  }))
-}));
-
-// Mock with partial implementation
-jest.mock('./config', () => ({
-  ...jest.requireActual('./config'),
-  API_KEY: 'test-key'
-}));
-```
-
-
----
-
-# Integration Testing
-
-## Testing Real Dependencies
-
-```typescript
-describe('UserRepository Integration', () => {
-  let db: Database;
-  let repository: UserRepository;
-
-  beforeAll(async () => {
-    db = await createTestDatabase();
-    repository = new UserRepository(db);
-  });
-
-  afterAll(async () => {
-    await db.close();
-  });
-
-  beforeEach(async () => {
-    await db.clear('users'); // Clean slate for each test
-  });
-
-  it('should persist and retrieve user', async () => {
-    const userData = { email: 'test@example.com', name: 'Test User' };
-
-    const created = await repository.create(userData);
-    const found = await repository.findById(created.id);
-
-    expect(found).toEqual(expect.objectContaining(userData));
-  });
-});
-```
-
-## API Integration Tests
-
-```typescript
-describe('POST /api/users', () => {
-  let app: Express;
-  let db: Database;
-
-  beforeAll(async () => {
-    db = await createTestDatabase();
-    app = createApp(db);
-  });
-
-  afterEach(async () => {
-    await db.clear('users');
-  });
-
-  it('should create user and return 201', async () => {
-    const response = await request(app)
-      .post('/api/users')
-      .send({ email: 'new@example.com', name: 'New User' })
-      .expect(201);
-
-    expect(response.body.data).toEqual(
-      expect.objectContaining({
-        email: 'new@example.com',
-        name: 'New User'
-      })
-    );
-
-    // Verify in database
-    const user = await db.findOne('users', { email: 'new@example.com' });
-    expect(user).toBeTruthy();
-  });
-
-  it('should return 400 for invalid email', async () => {
-    const response = await request(app)
-      .post('/api/users')
-      .send({ email: 'invalid', name: 'Test' })
-      .expect(400);
-
-    expect(response.body.error.code).toBe('VALIDATION_ERROR');
-  });
-});
-```
-
-## Database Transaction Testing
-
-```typescript
-describe('OrderService Integration', () => {
-  it('should rollback on payment failure', async () => {
-    const order = await orderService.createOrder({ items: [...] });
-
-    // Mock payment to fail
-    paymentGateway.charge.mockRejectedValue(new Error('Declined'));
-
-    await expect(
-      orderService.processOrder(order.id)
-    ).rejects.toThrow('Payment failed');
-
-    // Verify order status unchanged
-    const updatedOrder = await orderRepository.findById(order.id);
-    expect(updatedOrder.status).toBe('pending');
-
-    // Verify inventory not deducted
-    const inventory = await inventoryRepository.findByProductId(productId);
-    expect(inventory.quantity).toBe(originalQuantity);
-  });
-});
-```
-
-## Test Data Builders
-
-```typescript
-class UserBuilder {
-  private data: Partial<User> = {
-    email: 'default@example.com',
-    name: 'Default User',
-    role: 'user'
-  };
-
-  withEmail(email: string) { this.data.email = email; return this; }
-  withRole(role: string) { this.data.role = role; return this; }
-  asAdmin() { this.data.role = 'admin'; return this; }
-
-  build(): User { return this.data as User; }
-
-  async save(db: Database): Promise<User> {
-    return db.insert('users', this.data);
-  }
-}
-
-// Usage
-const admin = await new UserBuilder()
-  .withEmail('admin@example.com')
-  .asAdmin()
-  .save(db);
-```
-
-## Test Isolation
-
-```typescript
-// Use transactions that rollback
-describe('IntegrationTests', () => {
-  beforeEach(async () => {
-    await db.beginTransaction();
-  });
-
-  afterEach(async () => {
-    await db.rollbackTransaction();
-  });
-});
-
-// Or use test containers
-import { PostgreSqlContainer } from '@testcontainers/postgresql';
-
-let container: PostgreSqlContainer;
-
-beforeAll(async () => {
-  container = await new PostgreSqlContainer().start();
-  db = await connect(container.getConnectionUri());
-});
-
-afterAll(async () => {
-  await container.stop();
-});
-```
-
-
----
-
-# Testing Basics
-
-## Your First Unit Test
-
-A unit test verifies that a small piece of code works correctly.
-
-```pseudocode
-// Function to test
-function add(a, b):
-    return a + b
-
-// Test for the function
-test "add should sum two numbers":
-    result = add(2, 3)
-    expect result equals 5
-```
-
-## Test Structure
-
-Every test has three parts:
-
-1. **Setup** - Prepare what you need
-2. **Execute** - Run the code
-3. **Verify** - Check the result
-
-```pseudocode
-test "should create user with name":
-    // 1. Setup
-    userName = "Alice"
-
-    // 2. Execute
-    user = createUser(userName)
-
-    // 3. Verify
-    expect user.name equals "Alice"
-```
-
-## Common Assertions
-
-```pseudocode
-// Equality
-expect value equals 5
-expect value equals { id: 1 }
-
-// Truthiness
-expect value is truthy
-expect value is falsy
-expect value is null
-expect value is undefined
-
-// Numbers
-expect value > 3
-expect value < 10
-
-// Strings
-expect text contains "hello"
-
-// Arrays/Lists
-expect array contains item
-expect array length equals 3
-```
-
-## Testing Expected Errors
-
-```pseudocode
-test "should throw error for invalid input":
-    expect error when:
-        divide(10, 0)
-    with message "Cannot divide by zero"
-```
-
-## Async Tests
-
-```pseudocode
-test "should fetch user data" async:
-    user = await fetchUser(123)
-    expect user.id equals 123
-```
-
-## Test Naming
-
-Use clear, descriptive names:
-
-```pseudocode
-// ❌ Bad
-test "test1"
-test "it works"
-
-// ✅ Good
-test "should return user when ID exists"
-test "should throw error when ID is invalid"
-```
-
-## Running Tests
-
-```bash
-# Run all tests
-run-tests
-
-# Run specific test file
-run-tests user-test
-
-# Watch mode (re-run on changes)
-run-tests --watch
-```
-
-## Best Practices
-
-1. **One test, one thing** - Test one behavior per test
-2. **Independent tests** - Tests should not depend on each other
-3. **Clear names** - Name should describe what is being tested
-4. **Fast tests** - Tests should run quickly
-
-```pseudocode
-// ❌ Bad: Testing multiple things
-test "user operations":
-    expect createUser("Bob").name equals "Bob"
-    expect deleteUser(1) equals true
-    expect listUsers().length equals 0
-
-// ✅ Good: One test per operation
-test "should create user with given name":
-    user = createUser("Bob")
-    expect user.name equals "Bob"
-
-test "should delete user by ID":
-    result = deleteUser(1)
-    expect result equals true
-
-test "should return empty list when no users":
-    users = listUsers()
-    expect users.length equals 0
-```
-
-## When to Write Tests
-
-- **Before fixing bugs** - Write test that fails, then fix
-- **For new features** - Test expected behavior
-- **For edge cases** - Empty input, null values, large numbers
-
-## What to Test
-
-✅ **Do test:**
-- Public functions and methods
-- Edge cases (empty, null, zero, negative)
-- Error conditions
-
-❌ **Don't test:**
-- Private implementation details
-- Third-party libraries (they're already tested)
-- Getters/setters with no logic
-
-
----
-*Generated by aicgen*

package/.agent/workflows/add-documentation.md

@@ -1,10 +0,0 @@
----
-description: Add or update comprehensive documentation for code
----
-
-* Analyze the selected code for documentation needs
-* Add inline documentation with clear descriptions
-* Include parameter types and return value documentation
-* Add usage examples for complex functions
-* Follow language-specific documentation standards
-* Update README.md if adding new features

package/.agent/workflows/generate-integration-tests.md

@@ -1,10 +0,0 @@
----
-description: Generate integration tests for API endpoints and system components
----
-
-* Identify integration points (APIs, databases, services)
-* Create integration test files
-* Test end-to-end workflows
-* Use realistic test data and fixtures
-* Include proper setup and teardown
-* Ensure tests are idempotent

package/.agent/workflows/generate-unit-tests.md

@@ -1,11 +0,0 @@
----
-description: Generate comprehensive unit tests for all functions and methods
----
-
-* Analyze the selected file or directory for testable code
-* Generate test files with appropriate naming conventions
-* Create test cases covering happy path, edge cases, and error handling
-* Mock external dependencies appropriately
-* Follow language-specific testing best practices
-* Aim for >80% code coverage
-* Include setup and teardown methods where needed

package/.agent/workflows/performance-audit.md

@@ -1,11 +0,0 @@
----
-description: Analyze code for performance bottlenecks and optimization opportunities
----
-
-* Profile code to identify hotspots
-* Check for N+1 queries and inefficient algorithms
-* Analyze caching opportunities
-* Review resource management
-* Suggest specific optimizations
-* Estimate performance impact
-* Prioritize recommendations

package/.agent/workflows/refactor-extract-module.md

@@ -1,12 +0,0 @@
----
-description: Extract code into a separate, reusable module
----
-
-* Identify the code section to extract
-* Analyze dependencies and determine module interface
-* Create a new module file following project conventions
-* Maintain original functionality and behavior
-* Update imports and exports appropriately
-* Ensure no circular dependencies
-* Add documentation to the new module
-* Verify all tests still pass

package/.agent/workflows/security-audit.md

@@ -1,12 +0,0 @@
----
-description: Perform comprehensive security audit of the codebase
----
-
-* Scan for common vulnerabilities (SQL injection, XSS, etc.)
-* Check authentication and authorization logic
-* Review input validation and sanitization
-* Examine error handling for information leakage
-* Verify secure handling of sensitive data
-* Check third-party dependencies
-* Suggest remediation steps
-* Prioritize findings by severity