@paths.design/caws-cli 4.0.0 → 5.0.0

package/templates/.cursor/rules/13-implementation-completeness.mdc

@@ -0,0 +1,516 @@
+---
+description: Anti-fake implementation guardrails to prevent incomplete, stubbed, or fake implementations
+globs:
+alwaysApply: true
+---
+
+# Implementation Completeness Guardrails
+
+## Core Principle
+
+**No incomplete, stubbed, or fake implementations in production code.** All business logic must be fully implemented with proper error handling and real integrations.
+
+## Implementation Quality Detection
+
+### PLACEHOLDER Detection
+
+**Automated Detection Patterns:**
+
+```bash
+# Find all placeholder implementations
+rg -n "PLACEHOLDER|TODO|MOCK_DATA|FIXME|HACK" src/
+rg -n "throw new Error.*not implemented" src/
+rg -n "return.*mock|fake|dummy" src/
+rg -n "console\.log.*placeholder" src/
+```
+
+**Required Tagging:**
+
+```typescript
+// PLACEHOLDER: Real payment processing not implemented
+function processPayment(amount: number): Promise<PaymentResult> {
+  throw new Error('PLACEHOLDER: Payment processing not implemented');
+}
+
+// TODO: Implement actual tax calculation
+function calculateTax(amount: number): number {
+  if (process.env.NODE_ENV === 'production') {
+    throw new Error('TODO: Tax calculation must be implemented before production');
+  }
+  return amount * 0.1; // Mock calculation
+}
+
+// MOCK DATA: Remove before production
+const mockUsers = [{ id: 1, name: 'John Doe', email: 'john@example.com' }];
+```
+
+### Stub Implementation Prevention
+
+**Forbidden Patterns:**
+
+```typescript
+// ❌ BAD: Silent stub implementation
+function getUserData(id: string) {
+  return { id, name: 'Mock User' }; // No indication this is fake
+}
+
+// ❌ BAD: Console.log stub
+function processOrder(order: Order) {
+  console.log('Processing order:', order); // Not real implementation
+  return { success: true };
+}
+
+// ❌ BAD: Empty implementation
+function calculateTotal(items: Item[]) {
+  // Implementation coming soon
+  return 0;
+}
+```
+
+**Required Patterns:**
+
+```typescript
+// ✅ GOOD: Explicit placeholder with error
+function getUserData(id: string) {
+  // PLACEHOLDER: Real user data fetching not implemented
+  throw new Error('PLACEHOLDER: getUserData not implemented');
+}
+
+// ✅ GOOD: Proper implementation
+function processOrder(order: Order) {
+  const total = calculateTotal(order.items);
+  const tax = calculateTax(total);
+  return { success: true, total, tax };
+}
+```
+
+## Fake Persistence Detection
+
+### Database Mock Detection
+
+**Forbidden Patterns:**
+
+```typescript
+// ❌ BAD: In-memory "database"
+class UserRepository {
+  private users: User[] = []; // Not real persistence
+
+  async save(user: User) {
+    this.users.push(user); // Fake persistence
+  }
+}
+
+// ❌ BAD: Mock database operations
+async function createUser(userData: CreateUserRequest) {
+  // Mock database call
+  return { id: Math.random(), ...userData };
+}
+```
+
+**Required Patterns:**
+
+```typescript
+// ✅ GOOD: Real database implementation
+class UserRepository {
+  constructor(private db: Database) {}
+
+  async save(user: User) {
+    const result = await this.db.query(
+      'INSERT INTO users (name, email) VALUES ($1, $2) RETURNING *',
+      [user.name, user.email]
+    );
+    return result.rows[0];
+  }
+}
+```
+
+### API Mock Detection
+
+**Forbidden Patterns:**
+
+```typescript
+// ❌ BAD: Fake API responses
+async function fetchUserData(id: string) {
+  // Mock API response
+  return { id, name: 'Mock User', email: 'mock@example.com' };
+}
+
+// ❌ BAD: Hardcoded responses
+async function getWeatherData(city: string) {
+  return { city, temperature: 72, condition: 'sunny' }; // Fake data
+}
+```
+
+**Required Patterns:**
+
+```typescript
+// ✅ GOOD: Real API implementation
+async function fetchUserData(id: string) {
+  const response = await fetch(`/api/users/${id}`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch user: ${response.statusText}`);
+  }
+
+  return await response.json();
+}
+```
+
+## Business Logic Completeness
+
+### Core Business Functions
+
+**Must be fully implemented:**
+
+- Authentication and authorization
+- Data validation and sanitization
+- Business rule enforcement
+- Error handling and recovery
+- Audit logging and monitoring
+
+**Implementation Requirements:**
+
+```typescript
+// ✅ GOOD: Complete business logic
+class OrderService {
+  async processOrder(order: Order): Promise<OrderResult> {
+    // Validate input
+    if (!order.items || order.items.length === 0) {
+      throw new ValidationError('Order must contain items');
+    }
+
+    // Check inventory
+    const inventoryCheck = await this.inventoryService.checkAvailability(order.items);
+    if (!inventoryCheck.available) {
+      throw new InsufficientInventoryError(inventoryCheck.unavailableItems);
+    }
+
+    // Calculate pricing
+    const pricing = await this.pricingService.calculateOrder(order);
+
+    // Process payment
+    const payment = await this.paymentService.processPayment({
+      amount: pricing.total,
+      method: order.paymentMethod,
+    });
+
+    // Create order record
+    const orderRecord = await this.orderRepository.create({
+      ...order,
+      total: pricing.total,
+      paymentId: payment.id,
+      status: 'confirmed',
+    });
+
+    // Send confirmation
+    await this.notificationService.sendOrderConfirmation(orderRecord);
+
+    return {
+      orderId: orderRecord.id,
+      total: pricing.total,
+      estimatedDelivery: pricing.estimatedDelivery,
+    };
+  }
+}
+```
+
+## Quality Gates for Implementation
+
+### Pre-Production Checks
+
+**Automated Verification:**
+
+```bash
+# Check for incomplete implementations
+npm run check:completeness
+# - Scan for PLACEHOLDER/TODO/MOCK_DATA
+# - Verify all business logic is implemented
+# - Check for real database connections
+# - Validate API integrations
+
+# Check for fake persistence
+npm run check:persistence
+# - Verify database connections are real
+# - Check for in-memory storage patterns
+# - Validate migration scripts exist
+```
+
+### Implementation Completeness Matrix
+
+| Component           | Real DB     | Real APIs   | Error Handling | Validation  | Logging     |
+| ------------------- | ----------- | ----------- | -------------- | ----------- | ----------- |
+| **Auth**            | ✅ Required | ✅ Required | ✅ Required    | ✅ Required | ✅ Required |
+| **Billing**         | ✅ Required | ✅ Required | ✅ Required    | ✅ Required | ✅ Required |
+| **Data Processing** | ✅ Required | ✅ Required | ✅ Required    | ✅ Required | ✅ Required |
+| **UI Components**   | N/A         | ✅ Required | ✅ Required    | ✅ Required | Optional    |
+| **Utilities**       | N/A         | ✅ Required | ✅ Required    | ✅ Required | Optional    |
+
+## Advanced Detection Patterns
+
+### Hidden TODO Detection
+
+**High-Confidence Hidden TODO Patterns:**
+
+```python
+# Sophisticated patterns for detecting incomplete implementations
+high_confidence_patterns = {
+    'incomplete_implementation': [
+        r'\bnot\s+yet\s+implemented\b',
+        r'\bmissing\s+implementation\b',
+        r'\bincomplete\s+implementation\b',
+        r'\bpartial\s+implementation\b',
+        r'\bunimplemented\b',
+        r'\bnot\s+done\b',
+        r'\bpending\s+implementation\b',
+        r'\bto\s+be\s+implemented\b',
+        r'\bwill\s+be\s+implemented\b',
+    ],
+
+    'placeholder_code': [
+        r'\bplaceholder\s+code\b',
+        r'\bplaceholder\s+implementation\b',
+        r'\bstub\s+implementation\b',
+        r'\bdummy\s+implementation\b',
+        r'\bfake\s+implementation\b',
+        r'\bsimplified\s+.*?\s+implementation\b',
+        r'\bfor\s+now\b.*?(just|simply|only)\s+(concatenate|return|use)',
+    ],
+
+    'temporary_solutions': [
+        r'\btemporary\s+solution\b',
+        r'\btemporary\s+fix\b',
+        r'\bquick\s+fix\b',
+        r'\bworkaround\b',
+        r'\bhack\b.*?(fix|solution)',
+    ],
+
+    'hardcoded_values': [
+        r'\bhardcoded\s+value\b',
+        r'\bmagic\s+number\b',
+        r'\bmagic\s+string\b',
+        r'\bconstant\s+value\b.*?(replace|change|make\s+configurable)',
+    ],
+
+    'future_improvements': [
+        r'\bin\s+production\b.*?(implement|add|fix)',
+        r'\bin\s+a\s+real\s+implementation\b',
+        r'\beventually\b.*?(implement|add|fix)',
+        r'\bshould\s+be\b.*?(implemented|added|fixed)',
+        r'\bwould\s+be\b.*?(implemented|added|fixed)',
+    ],
+}
+```
+
+**Code Stub Detection:**
+
+```python
+# Language-specific stub patterns
+code_stub_patterns = {
+    'javascript': {
+        'function_stub': re.compile(r'^\s*(async\s+)?function\s+\w+\(.*\)\s*{'),
+        'throw_not_impl': re.compile(r"^\s*throw\s+new\s+Error\((\"|')(TODO|Not\s+Implemented)"),
+        'return_todo': re.compile(r"^\s*return\s+(null|undefined);\s*//\s*TODO"),
+    },
+    'typescript': {
+        'function_stub': re.compile(r'^\s*(async\s+)?function\s+\w+\(.*\)\s*{'),
+        'throw_not_impl': re.compile(r"^\s*throw\s+new\s+Error\((\"|')(TODO|Not\s+Implemented)"),
+        'return_todo': re.compile(r"^\s*return\s+(null|undefined);\s*//\s*TODO"),
+    },
+    'python': {
+        'function_stub': re.compile(r'^\s*def\s+\w+\(.*\):'),
+        'pass_stmt': re.compile(r'^\s*pass\s*$'),
+        'ellipsis_stmt': re.compile(r'^\s*\.\.\.\s*$'),
+        'raise_not_impl': re.compile(r'^\s*raise\s+NotImplementedError'),
+    },
+}
+```
+
+## Enforcement Mechanisms
+
+### Pre-Commit Hooks
+
+```bash
+# Check for incomplete implementations
+check-implementation-completeness() {
+  echo "🔍 Running implementation completeness check..."
+
+  # Check for placeholder implementations
+  local placeholders=$(git diff --cached | grep -E "PLACEHOLDER|TODO|MOCK_DATA" | wc -l)
+  if [ "$placeholders" -gt 0 ]; then
+    echo "❌ Found $placeholders placeholder implementations"
+    echo "All business logic must be fully implemented"
+    exit 1
+  fi
+
+  # Check for fake persistence patterns
+  local fake_persistence=$(git diff --cached | grep -E "private.*\[\]|mock.*database|fake.*persistence" | wc -l)
+  if [ "$fake_persistence" -gt 0 ]; then
+    echo "❌ Found $fake_persistence fake persistence patterns"
+    echo "Real database connections required"
+    exit 1
+  fi
+
+  echo "✅ No incomplete implementations found"
+}
+```
+
+### CI/CD Integration
+
+```yaml
+# Implementation completeness checks
+- name: Check Implementation Completeness
+  run: |
+    echo "🔍 Running implementation completeness analysis..."
+
+    # Check for placeholder implementations
+    placeholder_count=$(grep -r "PLACEHOLDER\|TODO\|MOCK_DATA" src/ | wc -l)
+    if [ "$placeholder_count" -gt 0 ]; then
+      echo "❌ Found $placeholder_count placeholder implementations"
+      echo "All business logic must be fully implemented"
+      exit 1
+    fi
+
+    # Check for fake persistence
+    fake_persistence_count=$(grep -r "private.*\[\]\|mock.*database\|fake.*persistence" src/ | wc -l)
+    if [ "$fake_persistence_count" -gt 0 ]; then
+      echo "❌ Found $fake_persistence_count fake persistence patterns"
+      echo "Real database connections required"
+      exit 1
+    fi
+
+    echo "✅ No incomplete implementations found"
+
+- name: Check for Hidden TODOs
+  run: |
+    # Use sophisticated pattern detection
+    hidden_todos=$(grep -r -E "(not yet implemented|missing implementation|incomplete implementation|partial implementation|unimplemented|not done|pending implementation|to be implemented|will be implemented)" src/ | wc -l)
+    if [ "$hidden_todos" -gt 0 ]; then
+      echo "❌ Found $hidden_todos hidden incomplete implementations"
+      echo "All implementations must be complete"
+      exit 1
+    fi
+
+    echo "✅ No hidden incomplete implementations found"
+```
+
+## Testing Requirements
+
+### Implementation Testing
+
+**Must test real implementations:**
+
+```typescript
+// ✅ GOOD: Test real database operations
+describe('UserRepository', () => {
+  let db: Database;
+
+  beforeEach(async () => {
+    db = await createTestDatabase();
+    await seedTestData(db);
+  });
+
+  afterEach(async () => {
+    await cleanupTestData(db);
+    await db.end();
+  });
+
+  it('should save user to database', async () => {
+    const user = { name: 'John Doe', email: 'john@example.com' };
+    const savedUser = await userRepository.save(user);
+
+    expect(savedUser.id).toBeDefined();
+    expect(savedUser.name).toBe(user.name);
+
+    // Verify in database
+    const dbUser = await db.query('SELECT * FROM users WHERE id = $1', [savedUser.id]);
+    expect(dbUser.rows[0]).toEqual(savedUser);
+  });
+});
+```
+
+**Forbidden test patterns:**
+
+```typescript
+// ❌ BAD: Mock the system under test
+jest.mock('./userRepository', () => ({
+  save: jest.fn(() => ({ id: 1, name: 'Mock User' })),
+}));
+
+// ❌ BAD: Test fake implementations
+test('save user', () => {
+  const result = userRepository.save({ name: 'John' });
+  expect(result.name).toBe('John'); // Tests mock, not real implementation
+});
+```
+
+## Quality Metrics
+
+### Implementation Completeness Score
+
+**Calculation Formula:**
+
+```python
+def calculate_completeness_score(analysis_results):
+    total_files = analysis_results['total_files']
+    files_with_todos = analysis_results['files_with_todos']
+    high_conf_todos = analysis_results['high_confidence_todos']
+
+    # Completeness score (higher is better)
+    completeness_score = 1.0 - (files_with_todos / total_files) if total_files > 0 else 1.0
+
+    # Quality score based on confidence levels
+    quality_score = 1.0 - (high_conf_todos / total_files) if total_files > 0 else 1.0
+
+    return {
+        'completeness_score': completeness_score,
+        'quality_score': quality_score,
+        'files_with_todos': files_with_todos,
+        'high_confidence_todos': high_conf_todos,
+        'total_files_analyzed': total_files
+    }
+```
+
+**Anti-Pattern Detection Metrics:**
+
+- **Placeholder Density**: Number of high-confidence TODOs per 1000 lines
+- **Stub Implementation Rate**: % of functions with stub patterns detected
+- **Temporary Solution Rate**: % of code marked as temporary/workaround
+- **Hardcoded Value Rate**: % of magic numbers/strings detected
+
+## Integration with CAWS
+
+### CAWS Quality Monitoring
+
+```bash
+# Use CAWS quality monitoring
+caws quality-monitor --action=code_edited --files="$(git diff --name-only)"
+
+# Track TODO resolution progress
+caws progress-update --criterion-id="TODO-001" --status="completed" --tests-passing=1
+```
+
+### Continuous Improvement
+
+**Monthly Audits:**
+
+```bash
+# Generate monthly completeness report
+grep -r "PLACEHOLDER\|TODO\|MOCK_DATA" src/ > monthly-todo-report.txt
+grep -r -E "(not yet implemented|missing implementation|incomplete implementation)" src/ > monthly-hidden-todos.txt
+
+# Track trends over time
+echo "Implementation completeness trends:" >> monthly-report.md
+echo "- Placeholder implementations: $(wc -l < monthly-todo-report.txt)" >> monthly-report.md
+echo "- Hidden incomplete implementations: $(wc -l < monthly-hidden-todos.txt)" >> monthly-report.md
+```
+
+**Quarterly Reviews:**
+
+- Full implementation audit across entire codebase
+- Review integration reality and persistence patterns
+- Update quality gates based on project evolution
+- Refine detection patterns based on new anti-patterns
+
+This rule ensures all implementations are complete, real, and production-ready, preventing the accumulation of incomplete or fake code that could cause production issues.