@paths.design/caws-cli 3.4.0 → 4.0.0

package/templates/.cursor/rules/02-testing-standards.mdc

@@ -0,0 +1,315 @@
+---
+description: Comprehensive testing standards and verification requirements
+globs:
+alwaysApply: true
+---
+
+# Testing Standards & Verification Requirements
+
+## Testing Pyramid Requirements
+
+### Unit Tests (Foundation Layer)
+
+- **Coverage Thresholds**: 80% line coverage, 90% branch coverage minimum
+- **Test Isolation**: Each test completely independent, no shared state
+- **Mock Strategy**: Mock external dependencies, test business logic in isolation
+- **Naming Convention**: `describe('ComponentName', () => { it('should do something', () => {}) })`
+- **Assertion Style**: Use descriptive assertions, avoid generic `toBe(true)`
+
+### Integration Tests (Middle Layer)
+
+- **Database Integration**: Real database connections, not mocked
+- **External APIs**: Test actual HTTP calls with proper error handling
+- **Component Communication**: Test inter-component contracts
+- **Setup/Teardown**: Proper database seeding and cleanup
+- **Async Handling**: All async operations properly awaited and tested
+
+### End-to-End Tests (Top Layer)
+
+- **Full User Journeys**: Complete workflows from start to finish
+- **Real Browsers**: Use actual browser automation, not mocked DOM
+- **Data Persistence**: Verify data survives application restarts
+- **Performance Baselines**: Include timing assertions where relevant
+
+## Test Quality Standards
+
+### Test Structure Requirements
+
+```typescript
+describe("ComponentName", () => {
+  describe("when condition A", () => {
+    it("should behave correctly", () => {
+      // Given: Setup preconditions
+      // When: Execute the action
+      // Then: Verify the outcome
+    });
+  });
+});
+```
+
+### Edge Case Coverage
+
+- **Null/Undefined**: Test with null, undefined, empty arrays, empty objects
+- **Boundary Values**: Test minimums, maximums, and edge boundaries
+- **Error Conditions**: Test all error paths and exception handling
+- **Concurrency**: Test race conditions and concurrent access
+- **Resource Limits**: Test memory limits, timeouts, rate limits
+
+### Test Data Management
+
+- **Realistic Fixtures**: Use representative data, not just minimal examples
+- **Factory Pattern**: Create test data factories for consistent object creation
+- **Cleanup Strategy**: Ensure tests don't leave persistent state
+- **Isolation**: Tests must not interfere with each other
+
+## Verification Requirements
+
+### Pre-Commit Verification
+
+- [ ] All unit tests pass (`npm test`)
+- [ ] No tests skipped in production code
+- [ ] Coverage thresholds met
+- [ ] No console errors or warnings in tests
+- [ ] Database tests use real connections
+
+### Integration Verification
+
+- [ ] Database schema matches migrations
+- [ ] External API contracts validated
+- [ ] Authentication/authorization tested
+- [ ] Error handling verified end-to-end
+
+### Performance Verification
+
+- [ ] Response times within documented SLAs
+- [ ] Memory usage within limits
+- [ ] Database query performance acceptable
+- [ ] Concurrent user load handled
+
+## Test Infrastructure Standards
+
+### Testing Tools & Frameworks
+
+- **Test Runner**: Jest, Vitest, or equivalent with parallel execution
+- **Assertion Library**: Built-in assertions with descriptive matchers
+- **Mocking**: Comprehensive mocking for external dependencies
+- **Coverage**: Istanbul/NYC for coverage reporting
+- **CI Integration**: Automated test execution in CI pipeline
+
+### Database Testing
+
+- **Test Database**: Separate database instance for tests
+- **Schema Sync**: Automatic schema setup/teardown
+- **Data Seeding**: Deterministic test data seeding
+- **Transaction Rollback**: Tests wrapped in transactions for cleanup
+
+### CI/CD Testing
+
+- **Parallel Execution**: Tests run in parallel for speed
+- **Flaky Test Detection**: Automatic retry for known flaky tests
+- **Coverage Reporting**: Coverage reports uploaded to CI
+- **Test Result Storage**: Historical test results tracked
+
+## Testing Anti-Patterns (Forbidden)
+
+### ❌ Mocking Core Business Logic
+
+```typescript
+// DON'T: Mock the function you're supposed to test
+jest.mock("./businessLogic", () => ({
+  calculateTotal: jest.fn(() => 100),
+}));
+
+test("calculateTotal", () => {
+  expect(calculateTotal()).toBe(100); // Tests the mock, not the logic
+});
+```
+
+### ❌ Testing Implementation Details
+
+```typescript
+// DON'T: Test private methods or internal state
+test("internal counter increments", () => {
+  component.privateCounter = 5; // Accessing private state
+  expect(component.privateCounter).toBe(5);
+});
+```
+
+### ❌ Inadequate Error Testing
+
+```typescript
+// DON'T: Generic error testing
+test("throws error", () => {
+  expect(() => riskyOperation()).toThrow(); // Too vague
+});
+```
+
+### ❌ No Cleanup in Integration Tests
+
+```typescript
+// DON'T: Leave test data behind
+test("creates user", async () => {
+  await createUser({ name: "test" });
+  // No cleanup - data persists
+});
+```
+
+## Testing Best Practices
+
+### ✅ Proper Error Testing
+
+```typescript
+test("throws specific error for invalid input", () => {
+  expect(() => validateEmail("invalid")).toThrow(ValidationError);
+  expect(() => validateEmail("invalid")).toThrow("Invalid email format");
+});
+```
+
+### ✅ Realistic Test Data
+
+```typescript
+const realisticUser = {
+  id: "user-123",
+  email: "user@example.com",
+  name: "John Doe",
+  createdAt: new Date("2024-01-01"),
+  preferences: { theme: "dark", notifications: true },
+};
+```
+
+### ✅ Proper Async Testing
+
+```typescript
+test("resolves with correct data", async () => {
+  const result = await fetchUserData("user-123");
+  expect(result).toEqual(expectedUserData);
+});
+```
+
+### ✅ Database Test Cleanup
+
+```typescript
+describe("UserService", () => {
+  let dbClient;
+
+  beforeEach(async () => {
+    dbClient = await createTestDbConnection();
+    await seedTestData(dbClient);
+  });
+
+  afterEach(async () => {
+    await cleanupTestData(dbClient);
+    await dbClient.end();
+  });
+});
+```
+
+## Test Documentation Requirements
+
+### Test Comments for Complex Logic
+
+```typescript
+test("calculates compound interest with monthly compounding", () => {
+  // Formula: A = P(1 + r/n)^(nt)
+  // Where: A = final amount, P = principal, r = rate, n = compounding frequency, t = time
+  const principal = 1000;
+  const rate = 0.05; // 5%
+  const compoundingFrequency = 12; // monthly
+  const timeInYears = 2;
+
+  const result = calculateCompoundInterest(
+    principal,
+    rate,
+    compoundingFrequency,
+    timeInYears
+  );
+  const expected = 1104.54; // Pre-calculated expected value
+
+  expect(result).toBeCloseTo(expected, 2);
+});
+```
+
+### Test Coverage Comments
+
+```typescript
+// Test Coverage:
+// ✅ Happy path: valid input -> correct output
+// ✅ Edge case: zero principal -> zero result
+// ✅ Edge case: negative rate -> throws error
+// ✅ Error case: invalid compounding frequency -> throws error
+// ✅ Boundary: very large numbers -> handles precision
+```
+
+## Performance Testing Standards
+
+### Response Time Assertions
+
+```typescript
+test("responds within SLA", async () => {
+  const startTime = Date.now();
+  const result = await expensiveOperation();
+  const duration = Date.now() - startTime;
+
+  expect(duration).toBeLessThan(5000); // 5 second SLA
+  expect(result).toBeDefined();
+});
+```
+
+### Load Testing Guidelines
+
+- Test with realistic concurrent users
+- Include warm-up periods
+- Measure 95th percentile response times
+- Test memory usage under load
+- Verify graceful degradation
+
+## Mutation Testing Standards
+
+### Mutation Operators to Cover
+
+- **Arithmetic Operators**: `+`, `-`, `*`, `/`, `%`
+- **Logical Operators**: `&&`, `||`, `!`
+- **Comparison Operators**: `==`, `!=`, `<`, `>`, `<=`, `>=`
+- **Conditional Boundaries**: `if` conditions, ternary operators
+- **Return Statements**: Missing/incorrect returns
+- **Variable Assignments**: Wrong variable assignments
+
+### Mutation Score Targets
+
+- **Critical Components**: 80%+ mutation score
+- **Business Logic**: 70%+ mutation score
+- **Utilities**: 60%+ mutation score
+- **UI Components**: 50%+ mutation score (may be lower due to test complexity)
+
+## Accessibility Testing (Web Components)
+
+### Screen Reader Testing
+
+```typescript
+test("is accessible to screen readers", () => {
+  render(<Button>Click me</Button>);
+
+  // Test ARIA labels
+  expect(screen.getByRole("button")).toHaveAttribute("aria-label", "Click me");
+
+  // Test keyboard navigation
+  userEvent.tab();
+  expect(screen.getByRole("button")).toHaveFocus();
+});
+```
+
+### Color Contrast Testing
+
+```typescript
+test("meets color contrast requirements", () => {
+  render(<Text variant="error">Error message</Text>);
+
+  const element = screen.getByText("Error message");
+  const styles = window.getComputedStyle(element);
+
+  // Verify contrast ratio programmatically
+  expect(
+    getContrastRatio(styles.color, styles.backgroundColor)
+  ).toBeGreaterThan(4.5);
+});
+```

package/templates/.cursor/rules/03-infrastructure-standards.mdc

@@ -0,0 +1,251 @@
+---
+description: Infrastructure, deployment, and operational standards
+globs:
+alwaysApply: true
+---
+
+# Infrastructure & Deployment Standards
+
+## Database Standards
+
+### Connection Management
+
+- **Connection Pooling**: Always use connection pools, never single connections
+- **Pool Configuration**: Set appropriate min/max connections based on load
+- **Timeout Handling**: Configure connection, query, and idle timeouts
+- **Health Checks**: Implement connection health validation
+- **Graceful Shutdown**: Properly close connections on application shutdown
+
+### Schema Management
+
+- **Migration Scripts**: Version-controlled, transactional migrations
+- **Downgrade Scripts**: Provide rollback migrations for all changes
+- **Idempotent Operations**: Migrations safe to run multiple times
+- **Testing**: All migrations tested against production-like data
+- **Documentation**: Migration purpose and impact clearly documented
+
+### Data Integrity
+
+- **Constraints**: Foreign keys, unique constraints, check constraints
+- **Transactions**: All multi-table operations in transactions
+- **Atomicity**: Either all changes succeed or all fail
+- **Consistency**: Database always in valid state
+- **Isolation**: Concurrent operations don't interfere
+
+## API Standards
+
+### RESTful Design
+
+- **Resource Naming**: Plural nouns, consistent casing
+- **HTTP Methods**: GET (read), POST (create), PUT/PATCH (update), DELETE
+- **Status Codes**: Proper HTTP status codes (200, 201, 400, 404, 500, etc.)
+- **Content Types**: JSON for data, appropriate content-type headers
+- **Versioning**: API versioning strategy (URL, headers, or content negotiation)
+
+### Error Handling
+
+- **Structured Errors**: Consistent error response format
+- **Error Codes**: Machine-readable error codes with human-readable messages
+- **Logging**: All errors logged with appropriate severity
+- **Client Guidance**: Error responses include actionable information
+- **No Information Leakage**: Sensitive information not exposed in errors
+
+## Security Standards
+
+### Authentication & Authorization
+
+- **Token Management**: Secure token storage and validation
+- **Session Handling**: Proper session lifecycle management
+- **Role-Based Access**: Clear role definitions and enforcement
+- **Permission Checking**: Every operation validates permissions
+- **Audit Logging**: All security events logged
+
+### Input Validation
+
+- **Schema Validation**: All inputs validated against schemas
+- **Sanitization**: User input sanitized before processing
+- **Type Safety**: Runtime type checking for external inputs
+- **Length Limits**: Reasonable limits on input sizes
+- **Content Filtering**: Malicious content detection and blocking
+
+## Monitoring & Observability
+
+### Logging Standards
+
+- **Structured Logging**: JSON format with consistent field names
+- **Log Levels**: ERROR, WARN, INFO, DEBUG appropriately used
+- **Context Information**: Request IDs, user context, operation details
+- **Performance Logging**: Response times, resource usage
+- **Error Correlation**: Related events linked together
+
+### Metrics Collection
+
+- **Business Metrics**: User registrations, API calls, conversion rates
+- **Performance Metrics**: Response times, throughput, error rates
+- **Resource Metrics**: CPU, memory, disk, network usage
+- **Custom Metrics**: Application-specific KPIs
+- **Alert Thresholds**: Defined thresholds for automated alerts
+
+### Health Checks
+
+- **Application Health**: Service availability and responsiveness
+- **Dependency Health**: Database, external APIs, message queues
+- **Resource Health**: Disk space, memory, connection pools
+- **Business Health**: Core business operations functional
+- **Automated Recovery**: Self-healing capabilities
+
+## Deployment Standards
+
+### Environment Configuration
+
+- **Environment Variables**: No hardcoded configuration values
+- **Configuration Files**: Version-controlled, environment-specific configs
+- **Secrets Management**: Secure storage and access for secrets
+- **Validation**: Configuration validated at startup
+- **Documentation**: All configuration options documented
+
+### Container Standards
+
+- **Base Images**: Minimal, secure base images
+- **Layer Optimization**: Efficient layer caching and ordering
+- **Security Scanning**: Container images scanned for vulnerabilities
+- **Resource Limits**: CPU and memory limits set appropriately
+- **Health Checks**: Container health checks implemented
+
+### CI/CD Pipeline
+
+- **Automated Testing**: Full test suite runs on every commit
+- **Security Scanning**: Automated security scans in pipeline
+- **Performance Testing**: Automated performance regression tests
+- **Deployment Automation**: Zero-touch deployment processes
+- **Rollback Capability**: Automated rollback procedures
+
+## Reliability Standards
+
+### Circuit Breaker Pattern
+
+- **Failure Threshold**: Configurable failure count before opening
+- **Recovery Timeout**: Time before attempting recovery
+- **Success Threshold**: Successes needed to close circuit
+- **Fallback Behavior**: Graceful degradation when circuit open
+- **Monitoring**: Circuit state and failure rates monitored
+
+### Retry Logic
+
+- **Exponential Backoff**: Increasing delay between retries
+- **Jitter**: Randomization to prevent thundering herd
+- **Maximum Retries**: Configurable retry limits
+- **Retry Conditions**: Only retry appropriate error types
+- **Circuit Integration**: Retry logic respects circuit breaker state
+
+### Graceful Degradation
+
+- **Feature Flags**: Ability to disable features under load
+- **Fallback Content**: Cached or simplified content when services fail
+- **Progressive Enhancement**: Core functionality works without extras
+- **User Communication**: Clear messaging about degraded functionality
+- **Automatic Recovery**: Services automatically recover when possible
+
+## Performance Standards
+
+### Response Time SLAs
+
+- **API Endpoints**: P95 response times defined and monitored
+- **Page Load Times**: Frontend performance budgets
+- **Database Queries**: Query performance thresholds
+- **Background Jobs**: Job completion time limits
+- **Real-time Operations**: Sub-second response requirements
+
+### Resource Management
+
+- **Memory Usage**: Monitor and limit memory consumption
+- **CPU Utilization**: Efficient CPU usage patterns
+- **Disk I/O**: Optimize file system operations
+- **Network Usage**: Efficient network communication
+- **Connection Pools**: Proper sizing of database and external connections
+
+### Caching Strategy
+
+- **Cache Invalidation**: Proper cache invalidation strategies
+- **Cache Penetration**: Protection against cache penetration attacks
+- **Cache Warming**: Proactive cache population for hot data
+- **Distributed Caching**: Scalable caching across multiple instances
+- **Cache Monitoring**: Cache hit rates and performance monitoring
+
+## Scalability Standards
+
+### Horizontal Scaling
+
+- **Stateless Design**: Applications designed for horizontal scaling
+- **Shared Nothing**: Instances don't share local state
+- **Load Balancing**: Proper load distribution across instances
+- **Session Management**: Distributed session storage
+- **Configuration**: Centralized configuration management
+
+### Database Scaling
+
+- **Read Replicas**: Read operations distributed across replicas
+- **Sharding Strategy**: Data partitioning strategy defined
+- **Connection Pooling**: Efficient connection management
+- **Query Optimization**: Efficient query patterns
+- **Indexing Strategy**: Appropriate indexes for query patterns
+
+### Asynchronous Processing
+
+- **Message Queues**: Asynchronous task processing
+- **Background Jobs**: Long-running tasks processed asynchronously
+- **Event-Driven Architecture**: Loose coupling through events
+- **Dead Letter Queues**: Handling of failed message processing
+- **Monitoring**: Queue depth and processing rate monitoring
+
+## Backup & Recovery
+
+### Data Backup
+
+- **Regular Backups**: Automated backup schedules
+- **Backup Verification**: Backup integrity validation
+- **Retention Policies**: Backup retention periods defined
+- **Encryption**: Backup data encrypted at rest and in transit
+- **Testing**: Backup restoration regularly tested
+
+### Disaster Recovery
+
+- **Recovery Time Objective (RTO)**: Maximum acceptable downtime
+- **Recovery Point Objective (RPO)**: Maximum data loss acceptable
+- **Multi-Region Deployment**: Geographic redundancy
+- **Failover Procedures**: Automated and manual failover processes
+- **Recovery Testing**: Regular disaster recovery drills
+
+### Business Continuity
+
+- **Service Level Agreements**: Defined uptime and performance guarantees
+- **Incident Response**: Defined incident response procedures
+- **Communication Plans**: Stakeholder communication during incidents
+- **Post-Mortem Process**: Incident analysis and improvement process
+- **Continuous Improvement**: Regular review and improvement of processes
+
+## Compliance & Governance
+
+### Security Compliance
+
+- **Data Encryption**: Data encrypted at rest and in transit
+- **Access Controls**: Principle of least privilege enforced
+- **Audit Trails**: Comprehensive audit logging
+- **Vulnerability Management**: Regular security assessments
+- **Incident Response**: Security incident response procedures
+
+### Data Privacy
+
+- **Data Classification**: Sensitive data properly classified
+- **Retention Policies**: Data retention periods defined
+- **Consent Management**: User consent properly managed
+- **Data Deletion**: Right to deletion implemented
+- **Privacy Impact Assessments**: Privacy risks assessed
+
+### Regulatory Compliance
+
+- **GDPR Compliance**: EU data protection regulations
+- **CCPA Compliance**: California consumer privacy regulations
+- **Industry Standards**: Relevant industry compliance requirements
+- **Audit Readiness**: Systems designed for regulatory audits
+- **Documentation**: Compliance evidence properly documented