metacoding 1.0.0 → 1.1.1

package/templates/node/nodejs.testing.instructions.md

@@ -0,0 +1,373 @@
+---
+description: 'Node.js backend testing strategies and frameworks'
+applyTo: 'test/**/*.{ts,js}'
+---
+
+# Node.js Backend Testing Guidelines
+
+## Test Case Naming Conventions
+
+### Test Case ID Format: `[AREA]-[TYPE]-[NUMBER]`
+
+**Node.js/Backend Area Prefixes:**
+
+- `API` - REST API endpoint tests
+- `SRV` - Service layer tests
+- `DB` - Database/ORM tests
+- `AUTH` - Authentication/Authorization tests
+- `UTIL` - Backend utility function tests
+- `CONFIG` - Configuration management tests
+- `MIDDLEWARE` - Express middleware tests
+- `QUEUE` - Message queue/job processing tests
+- `CACHE` - Caching layer tests
+- `VALIDATION` - Input validation tests
+
+**Type Suffixes:**
+
+- `UNIT` - Unit tests (isolated component testing)
+- `INT` - Integration tests (component interaction testing)
+- `E2E` - End-to-end tests (full API workflow testing)
+
+**Examples:**
+
+- `API-UNIT-001` - First unit test for API endpoint
+- `SRV-UNIT-001` - First unit test for Service layer
+- `DB-INT-001` - First integration test for Database layer
+- `AUTH-E2E-001` - First end-to-end authentication test
+
+## Testing Strategy Overview
+
+### Testing Pyramid for Node.js Backend
+
+- **Unit Tests (70%):** Test individual functions and modules in isolation
+- **Integration Tests (20%):** Test interactions between components
+- **End-to-End Tests (10%):** Test complete user workflows through APIs
+- **Contract Tests:** Verify API contracts and external service interactions
+
+### Test Framework Selection
+
+- **Primary Framework:** Jest for unit and integration testing
+- **API Testing:** Supertest for HTTP endpoint testing
+- **Database Testing:** Test containers or in-memory databases
+- **Mocking:** Jest mocks for external dependencies
+- **Load Testing:** Artillery or k6 for performance testing
+
+## Unit Testing Best Practices
+
+### Test Structure and Organization
+
+- **Test File Naming:** Use `.test.ts` or `.spec.ts` suffix
+- **Test Grouping:** Group related tests using `describe` blocks
+- **Test Isolation:** Each test should be independent and idempotent
+- **Test Data:** Use factories or builders for test data creation
+- **Test Cleanup:** Clean up resources after each test
+
+```typescript
+// Example test structure
+describe('UserService', () => {
+  let userService: UserService;
+  let mockRepository: jest.Mocked<UserRepository>;
+
+  beforeEach(() => {
+    mockRepository = createMockRepository();
+    userService = new UserService(mockRepository);
+  });
+
+  describe('createUser', () => {
+    it('should create a user with valid data', async () => {
+      // Arrange
+      const userData = UserFactory.build();
+      mockRepository.save.mockResolvedValue(userData);
+
+      // Act
+      const result = await userService.createUser(userData);
+
+      // Assert
+      expect(result).toEqual(userData);
+      expect(mockRepository.save).toHaveBeenCalledWith(userData);
+    });
+
+    it('should throw ValidationError for invalid email', async () => {
+      // Arrange
+      const invalidUserData = UserFactory.build({ email: 'invalid-email' });
+
+      // Act & Assert
+      await expect(userService.createUser(invalidUserData)).rejects.toThrow(
+        ValidationError
+      );
+    });
+  });
+});
+```
+
+### Mocking Strategies
+
+- **External Dependencies:** Mock all external services and databases
+- **File System Operations:** Mock file system interactions
+- **Time-Dependent Code:** Mock dates and timers
+- **Environment Variables:** Mock configuration and environment
+- **HTTP Requests:** Mock external API calls
+
+```typescript
+// Example mocking patterns
+jest.mock('fs-extra');
+jest.mock('../services/email-service');
+
+const mockFs = fs as jest.Mocked<typeof fs>;
+const mockEmailService = EmailService as jest.MockedClass<typeof EmailService>;
+
+describe('FileProcessor', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockFs.readFile.mockResolvedValue('file content');
+  });
+});
+```
+
+## Integration Testing
+
+### Database Testing
+
+- **Test Database:** Use separate test database or test containers
+- **Transaction Rollback:** Rollback transactions after each test
+- **Seed Data:** Create consistent test data sets
+- **Migration Testing:** Test database migrations
+- **Performance Testing:** Test query performance
+
+```typescript
+// Example database integration test
+describe('UserRepository Integration', () => {
+  let repository: UserRepository;
+  let connection: Connection;
+
+  beforeAll(async () => {
+    connection = await createTestConnection();
+    repository = new UserRepository(connection);
+  });
+
+  afterAll(async () => {
+    await connection.close();
+  });
+
+  beforeEach(async () => {
+    await connection.synchronize(true); // Reset database
+  });
+
+  it('should save and retrieve user correctly', async () => {
+    // Arrange
+    const userData = UserFactory.build();
+
+    // Act
+    const savedUser = await repository.save(userData);
+    const retrievedUser = await repository.findById(savedUser.id);
+
+    // Assert
+    expect(retrievedUser).toEqual(savedUser);
+  });
+});
+```
+
+### API Endpoint Testing
+
+- **HTTP Testing:** Use Supertest for endpoint testing
+- **Authentication Testing:** Test auth middleware and permissions
+- **Validation Testing:** Test request validation and error responses
+- **Response Format:** Verify response structure and data types
+- **Status Code Testing:** Test all possible HTTP status codes
+
+```typescript
+// Example API endpoint test
+describe('POST /api/v1/users', () => {
+  let app: Application;
+
+  beforeAll(() => {
+    app = createTestApp();
+  });
+
+  it('should create user with valid data', async () => {
+    // Arrange
+    const userData = UserFactory.build();
+
+    // Act
+    const response = await request(app)
+      .post('/api/v1/users')
+      .send(userData)
+      .expect(201);
+
+    // Assert
+    expect(response.body.success).toBe(true);
+    expect(response.body.data.email).toBe(userData.email);
+  });
+
+  it('should return 400 for invalid email', async () => {
+    // Arrange
+    const invalidData = UserFactory.build({ email: 'invalid' });
+
+    // Act
+    const response = await request(app)
+      .post('/api/v1/users')
+      .send(invalidData)
+      .expect(400);
+
+    // Assert
+    expect(response.body.success).toBe(false);
+    expect(response.body.error.code).toBe('VALIDATION_ERROR');
+  });
+});
+```
+
+## End-to-End Testing
+
+### Full Workflow Testing
+
+- **User Scenarios:** Test complete user journeys
+- **Multi-Service Testing:** Test interactions between services
+- **Real Database:** Use real database for E2E tests
+- **External Services:** Use real or staging external services
+- **Browser Testing:** Test web interfaces if applicable
+
+### Authentication and Authorization Testing
+
+- **Login Flows:** Test complete authentication flows
+- **Token Management:** Test token generation and validation
+- **Permission Testing:** Test role-based access control
+- **Session Management:** Test session creation and cleanup
+- **Security Testing:** Test for common security vulnerabilities
+
+## Performance Testing
+
+### Load Testing Strategies
+
+- **Baseline Performance:** Establish performance baselines
+- **Stress Testing:** Test system limits and breaking points
+- **Spike Testing:** Test sudden load increases
+- **Volume Testing:** Test with large amounts of data
+- **Endurance Testing:** Test sustained load over time
+
+```javascript
+// Example Artillery load test configuration
+config:
+  target: 'http://localhost:3000'
+  phases:
+    - duration: 60
+      arrivalRate: 10
+    - duration: 120
+      arrivalRate: 50
+    - duration: 60
+      arrivalRate: 10
+
+scenarios:
+  - name: 'User Creation Flow'
+    weight: 70
+    flow:
+      - post:
+          url: '/api/v1/users'
+          json:
+            email: '{{ $randomEmail() }}'
+            name: '{{ $randomString() }}'
+      - think: 1
+
+  - name: 'User Retrieval'
+    weight: 30
+    flow:
+      - get:
+          url: '/api/v1/users/{{ userId }}'
+```
+
+### Database Performance Testing
+
+- **Query Performance:** Test slow query detection
+- **Connection Pool Testing:** Test connection pool limits
+- **Transaction Performance:** Test transaction overhead
+- **Index Effectiveness:** Test query optimization
+- **Data Volume Testing:** Test with production-like data volumes
+
+## Test Data Management
+
+### Test Factories and Builders
+
+- **Data Factories:** Create consistent test data
+- **Builder Pattern:** Flexible test data creation
+- **Realistic Data:** Use realistic but not real user data
+- **Data Relationships:** Handle related entity creation
+- **Data Cleanup:** Ensure test data doesn't leak between tests
+
+```typescript
+// Example test factory
+export class UserFactory {
+  static build(overrides: Partial<User> = {}): User {
+    return {
+      id: faker.string.uuid(),
+      email: faker.internet.email(),
+      name: faker.person.fullName(),
+      createdAt: new Date(),
+      updatedAt: new Date(),
+      ...overrides,
+    };
+  }
+
+  static buildMany(count: number, overrides?: Partial<User>): User[] {
+    return Array.from({ length: count }, () => this.build(overrides));
+  }
+}
+```
+
+### Database Seeding and Fixtures
+
+- **Seed Scripts:** Create consistent database states
+- **Fixture Management:** Manage test fixture lifecycle
+- **Data Isolation:** Prevent test data interference
+- **Cleanup Strategies:** Efficient test cleanup procedures
+- **Snapshot Testing:** Use database snapshots for complex scenarios
+
+## Security Testing
+
+### Authentication Testing
+
+- **Token Validation:** Test JWT token validation
+- **Password Security:** Test password hashing and validation
+- **Brute Force Protection:** Test rate limiting and account lockout
+- **Session Security:** Test session hijacking prevention
+- **Multi-Factor Authentication:** Test MFA implementation
+
+### Authorization Testing
+
+- **Role-Based Access:** Test different user roles and permissions
+- **Resource Access:** Test access to protected resources
+- **Privilege Escalation:** Test prevention of privilege escalation
+- **Cross-Tenant Access:** Test multi-tenant isolation
+- **API Security:** Test API authentication and authorization
+
+### Vulnerability Testing
+
+- **Input Validation:** Test for injection attacks
+- **Cross-Site Scripting:** Test XSS prevention
+- **Cross-Site Request Forgery:** Test CSRF protection
+- **Dependency Scanning:** Test for vulnerable dependencies
+- **Security Headers:** Test security header implementation
+
+## Test Environment Management
+
+### Environment Isolation
+
+- **Test Containers:** Use Docker containers for isolation
+- **Environment Variables:** Manage test-specific configuration
+- **Service Mocking:** Mock external services appropriately
+- **Database Isolation:** Separate test databases
+- **Network Isolation:** Isolate test network traffic
+
+### Continuous Integration Testing
+
+- **Pipeline Integration:** Run tests in CI/CD pipelines
+- **Parallel Testing:** Run tests in parallel for speed
+- **Test Reporting:** Generate comprehensive test reports
+- **Coverage Reporting:** Track and report test coverage
+- **Failure Analysis:** Analyze and debug test failures
+
+### Test Monitoring and Metrics
+
+- **Test Performance:** Monitor test execution time
+- **Flaky Test Detection:** Identify and fix unreliable tests
+- **Coverage Trends:** Track test coverage over time
+- **Test Maintenance:** Regularly review and update tests
+- **Quality Gates:** Enforce quality standards through testing

package/templates/python/python.coding.instructions.md

@@ -0,0 +1,339 @@
+---
+description: 'Python-specific coding standards and best practices'
+applyTo: '**/*.py'
+language: 'python'
+---
+
+# Python Coding Standards and Best Practices
+
+## Language and Framework Preferences
+
+- **Primary Language:** Python 3.9+ for all Python projects
+- **Code Style:** Follow PEP 8 with Black formatter for consistent formatting
+- **Type Hints:** Use type hints for all function signatures and complex variables
+- **Target Compatibility:** Python 3.9+ (use modern Python features appropriately)
+
+## Code Quality Guidelines
+
+- **Readability:** Follow "The Zen of Python" - explicit is better than implicit
+- **Functions:** Keep functions focused, ideally under 30 lines for better readability
+- **Magic Numbers:** Use named constants or configuration files instead of magic numbers
+- **Error Handling:** Use specific exception types, avoid bare `except:` clauses
+- **Memory Management:** Be mindful of memory usage, use generators for large datasets
+- **Async Patterns:** Use `asyncio` for I/O-bound operations, avoid blocking operations
+
+## Naming Conventions
+
+- **Files:** Use snake_case for file names (e.g., `user_service.py`)
+- **Classes:** PascalCase (e.g., `UserService`, `DatabaseConnection`)
+- **Functions/Methods:** snake_case (e.g., `get_user_by_id`, `validate_input`)
+- **Variables:** snake_case (e.g., `user_id`, `is_valid`)
+- **Constants:** SCREAMING_SNAKE_CASE (e.g., `MAX_RETRY_ATTEMPTS`, `DEFAULT_TIMEOUT`)
+- **Private Attributes:** Single underscore prefix (e.g., `_internal_method`)
+- **Name Mangling:** Double underscore prefix only when necessary (e.g., `__private_attr`)
+
+## Code Organization
+
+- **Single Responsibility:** One class per file for complex classes, related utilities can be grouped
+- **Imports:** Follow PEP 8 import order (standard library, third-party, local imports)
+- **Module Structure:** Use `__init__.py` files for package initialization and clean imports
+- **Entry Points:** Use `if __name__ == "__main__":` for script entry points
+
+## Python-Specific Best Practices
+
+### Type Hints and Documentation
+
+```python
+from typing import List, Dict, Optional, Union
+from dataclasses import dataclass
+
+def process_user_data(
+    users: List[Dict[str, Union[str, int]]],
+    active_only: bool = True
+) -> List[str]:
+    """Process user data and return list of usernames.
+
+    Args:
+        users: List of user dictionaries containing user information
+        active_only: If True, only include active users
+
+    Returns:
+        List of usernames matching the criteria
+
+    Raises:
+        ValueError: If user data format is invalid
+    """
+    pass
+```
+
+### Error Handling Patterns
+
+```python
+# Good: Specific exception handling
+try:
+    user = get_user_by_id(user_id)
+except UserNotFoundError as e:
+    logger.warning(f"User {user_id} not found: {e}")
+    return None
+except DatabaseConnectionError as e:
+    logger.error(f"Database connection failed: {e}")
+    raise
+
+# Good: Use custom exceptions
+class ValidationError(Exception):
+    """Raised when data validation fails."""
+    pass
+
+class UserNotFoundError(Exception):
+    """Raised when requested user cannot be found."""
+    pass
+```
+
+### Resource Management
+
+```python
+# Good: Use context managers
+with open('data.json', 'r') as file:
+    data = json.load(file)
+
+# Good: Create custom context managers when needed
+from contextlib import contextmanager
+
+@contextmanager
+def database_transaction():
+    conn = get_connection()
+    trans = conn.begin()
+    try:
+        yield conn
+        trans.commit()
+    except Exception:
+        trans.rollback()
+        raise
+    finally:
+        conn.close()
+```
+
+### Performance Considerations
+
+```python
+# Good: Use generators for large datasets
+def process_large_file(filename: str):
+    with open(filename, 'r') as file:
+        for line in file:
+            yield process_line(line)
+
+# Good: Use list comprehensions for simple transformations
+active_users = [user for user in users if user.is_active]
+
+# Good: Use appropriate data structures
+from collections import defaultdict, deque
+user_groups = defaultdict(list)
+```
+
+## Testing Standards
+
+### Test Framework Preferences
+
+- **Primary Framework:** pytest for all testing
+- **Fixtures:** Use pytest fixtures for test data and setup
+- **Parametrized Tests:** Use `pytest.mark.parametrize` for multiple test cases
+- **Mocking:** Use `unittest.mock` or `pytest-mock` for mocking dependencies
+
+### Test File Organization
+
+```python
+# tests/test_user_service.py
+import pytest
+from unittest.mock import Mock, patch
+from src.services.user_service import UserService
+from src.exceptions import UserNotFoundError
+
+class TestUserService:
+    @pytest.fixture
+    def user_service(self):
+        return UserService(db_connection=Mock())
+
+    @pytest.mark.parametrize("user_id,expected", [
+        (1, True),
+        (999, False),
+    ])
+    def test_user_exists(self, user_service, user_id, expected):
+        # Test implementation
+        pass
+
+    def test_get_user_not_found_raises_exception(self, user_service):
+        with pytest.raises(UserNotFoundError):
+            user_service.get_user_by_id(999)
+```
+
+## Dependency Management
+
+### Package Management
+
+- **Primary Tool:** Poetry for dependency management and packaging
+- **Requirements:** Maintain both `pyproject.toml` and `requirements.txt`
+- **Development Dependencies:** Separate dev dependencies (testing, linting, formatting)
+- **Version Pinning:** Pin exact versions for applications, use ranges for libraries
+
+### Virtual Environment Management
+
+```bash
+# Create and activate virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Or use Poetry
+poetry install
+poetry shell
+```
+
+## Code Quality Tools
+
+### Linting and Formatting
+
+- **Black:** Code formatting with line length 88
+- **isort:** Import sorting and organization
+- **flake8:** Linting and style checking
+- **mypy:** Static type checking
+- **pylint:** Additional code analysis
+
+### Configuration Examples
+
+```toml
+# pyproject.toml
+[tool.black]
+line-length = 88
+target-version = ['py39']
+
+[tool.isort]
+profile = "black"
+multi_line_output = 3
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+ignore_missing_imports = true
+```
+
+## Documentation Standards
+
+### Docstring Format
+
+Use Google-style docstrings:
+
+```python
+def calculate_user_score(
+    user_data: Dict[str, Any],
+    weights: Optional[Dict[str, float]] = None
+) -> float:
+    """Calculate a user's composite score based on various metrics.
+
+    This function computes a weighted score based on user activity,
+    engagement, and other factors.
+
+    Args:
+        user_data: Dictionary containing user metrics and information
+        weights: Optional custom weights for score calculation.
+                Defaults to standard weights if not provided.
+
+    Returns:
+        Calculated score as a float between 0.0 and 100.0
+
+    Raises:
+        ValueError: If user_data is missing required fields
+        TypeError: If weights contain non-numeric values
+
+    Example:
+        >>> user = {"activity": 85, "engagement": 92}
+        >>> calculate_user_score(user)
+        88.5
+    """
+    pass
+```
+
+## Security Considerations
+
+### Input Validation
+
+```python
+import re
+from typing import Any
+
+def validate_email(email: str) -> bool:
+    """Validate email format using regex."""
+    pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
+    return bool(re.match(pattern, email))
+
+def sanitize_user_input(user_input: str) -> str:
+    """Sanitize user input to prevent injection attacks."""
+    # Remove potentially dangerous characters
+    safe_input = re.sub(r'[<>"\';]', '', user_input)
+    return safe_input.strip()
+```
+
+### Environment Configuration
+
+```python
+import os
+from dataclasses import dataclass
+
+@dataclass
+class Config:
+    """Application configuration from environment variables."""
+    database_url: str = os.getenv('DATABASE_URL', 'sqlite:///default.db')
+    secret_key: str = os.getenv('SECRET_KEY', 'dev-key-change-in-production')
+    debug: bool = os.getenv('DEBUG', 'False').lower() == 'true'
+
+    def __post_init__(self):
+        if self.secret_key == 'dev-key-change-in-production' and not self.debug:
+            raise ValueError("SECRET_KEY must be set in production")
+```
+
+## Common Anti-Patterns to Avoid
+
+- **Mutable Default Arguments:** Use `None` and check inside function
+- **Broad Exception Catching:** Avoid bare `except:` clauses
+- **Global Variables:** Minimize global state, use dependency injection
+- **String Concatenation in Loops:** Use `join()` for multiple strings
+- **Not Using Context Managers:** Always use `with` for file operations
+- **Ignoring PEP 8:** Follow Python style guidelines consistently
+- **Missing Type Hints:** Add type hints for better code documentation
+- **Circular Imports:** Structure modules to avoid circular dependencies
+
+## Performance Optimization
+
+### Memory Efficiency
+
+```python
+# Use generators for large datasets
+def read_large_file(filename: str):
+    with open(filename, 'r') as file:
+        for line in file:
+            yield line.strip()
+
+# Use __slots__ for classes with many instances
+class Point:
+    __slots__ = ['x', 'y']
+
+    def __init__(self, x: float, y: float):
+        self.x = x
+        self.y = y
+```
+
+### Concurrency Patterns
+
+```python
+import asyncio
+from concurrent.futures import ThreadPoolExecutor
+
+async def process_data_async(data_list: List[str]) -> List[str]:
+    """Process data asynchronously for I/O bound operations."""
+    tasks = [process_item_async(item) for item in data_list]
+    return await asyncio.gather(*tasks)
+
+def process_cpu_intensive_data(data_list: List[str]) -> List[str]:
+    """Use thread pool for CPU-intensive operations."""
+    with ThreadPoolExecutor(max_workers=4) as executor:
+        results = list(executor.map(cpu_intensive_process, data_list))
+    return results
+```