metacoding 1.0.0 → 1.1.1

package/templates/react/test-runner.instructions.md

@@ -0,0 +1,135 @@
+---
+description: 'React/Frontend testing guidelines and workflow'
+applyTo: 'test/**/*'
+---
+
+# React/Frontend Test Execution Guidelines
+
+## Pre-Commit Testing Workflow
+
+- **Run all tests before committing changes:** Use `npm test` or `yarn test`
+- **Ensure tests pass in both development and CI environments**
+- **Fix failing tests before proceeding with commits**
+- **Run specific test suites for targeted changes when appropriate**
+- **Verify test coverage meets project standards**
+
+## Test Development Standards
+
+- **New Features:** Ensure all new React components have corresponding unit tests
+- **Test Coverage:** Aim for high coverage of critical functionality paths
+- **Test Documentation:** Follow standardized table format in `test/test-documentation.md` for all test cases
+- **Test Organization:** Group related tests with clear hierarchy and descriptive names
+- **React-Specific Patterns:** Follow React Testing Library patterns and best practices
+
+## React/Frontend Testing Guidelines
+
+For detailed React testing frameworks and patterns, refer to:
+
+- **React Testing Library:** Component testing with user-centric approach
+- **Jest:** Unit testing framework with snapshot testing
+- **Cypress/Playwright:** End-to-end testing for user workflows
+- **Storybook:** Component documentation and visual testing
+
+## Test Case Documentation Format
+
+All test cases must be documented using the standardized table format:
+
+```markdown
+| Test Case ID  | Description                                 | Type | Status    |
+| :------------ | :------------------------------------------ | :--- | :-------- |
+| AREA-TYPE-001 | Brief but descriptive test case description | Unit | Completed |
+```
+
+## React/Frontend Test Case Naming Conventions
+
+### Test Case ID Format: `[AREA]-[TYPE]-[NUMBER]`
+
+**React/Frontend Area Prefixes:**
+
+- `COMP` - React component tests
+- `HOOK` - Custom hooks tests
+- `PAGE` - Page/Route component tests
+- `UTIL` - Frontend utility function tests
+- `STORE` - State management tests (Redux/Zustand/Context)
+- `API` - Frontend API client tests
+- `FORM` - Form validation and submission tests
+- `UI` - UI interaction and behavior tests
+- `A11Y` - Accessibility compliance tests
+- `PERF` - Performance and optimization tests
+
+**Type Suffixes:**
+
+- `UNIT` - Unit tests (isolated component testing)
+- `INT` - Integration tests (component interaction testing)
+- `E2E` - End-to-end tests (full user workflow testing)
+
+**Examples:**
+
+- `COMP-UNIT-001` - First unit test for React Component
+- `HOOK-UNIT-001` - First unit test for Custom Hook
+- `PAGE-E2E-001` - First end-to-end test for Page Component
+- `FORM-INT-001` - First integration test for Form Component
+
+### Test Method Naming
+
+Use React-specific naming conventions:
+
+- **Component Tests:** `ComponentName_scenario_expectedOutcome`
+- **Hook Tests:** `useHookName_scenario_expectedOutcome`
+- **Consistent Pattern:** Always include what's being tested, the scenario, and expected result
+
+## React-Specific Test Data Management
+
+- **Component Props:** Use realistic props that match production data
+- **Mock Data:** Create mock data that represents actual API responses
+- **User Events:** Simulate realistic user interactions (clicks, typing, navigation)
+- **Async Operations:** Properly test loading states and async data fetching
+- **Temporary File Cleanup:** Clean up all temporary test files, screenshots, and debug outputs after test execution
+- **Mock Cleanup:** Properly reset mocks between tests to avoid test pollution
+
+## Test File Hygiene
+
+- **No Orphaned Files:** Remove temporary test files created during debugging or development
+- **Debug Output Cleanup:** Remove console output statements and debug files before committing
+- **Test Artifact Management:** Ensure test screenshots, coverage reports, and logs are properly managed
+- **Resource Management:** Properly dispose of DOM elements, event listeners, and other test resources
+- **Documentation Updates:** Remove temporary test documentation and move useful content to proper locations
+
+## React Component Testing Patterns
+
+### Component Unit Tests
+
+- **Render Testing:** Verify components render without crashing
+- **Props Testing:** Test component behavior with different prop combinations
+- **State Testing:** Test component state changes and updates
+- **Event Testing:** Test user interaction handling
+- **Snapshot Testing:** Maintain component structure consistency
+
+### Custom Hook Testing
+
+- **Hook Logic:** Test hook functionality in isolation
+- **State Management:** Test hook state updates and side effects
+- **Dependencies:** Test hook behavior with different dependencies
+- **Error Handling:** Test hook error scenarios and recovery
+
+### Integration Testing
+
+- **Component Interaction:** Test how components work together
+- **Data Flow:** Test data passing between parent and child components
+- **Context Providers:** Test components within context providers
+- **Router Integration:** Test routing and navigation behavior
+
+### End-to-End Testing
+
+- **User Workflows:** Test complete user journeys through the application
+- **Cross-Browser:** Test functionality across different browsers
+- **Responsive Design:** Test application behavior on different screen sizes
+- **Performance:** Test application performance under load
+
+## Common React Testing Anti-Patterns to Avoid
+
+- **Testing Implementation Details:** Focus on user behavior, not internal state
+- **Shallow Rendering:** Prefer full rendering with React Testing Library
+- **Overmocking:** Mock only external dependencies, not internal components
+- **Snapshot Overuse:** Use snapshots sparingly for UI consistency checks
+- **Ignoring Accessibility:** Always test for accessibility compliance

package/templates/typescript/template.json

@@ -0,0 +1,16 @@
+{
+  "name": "typescript",
+  "description": "Shared TypeScript instructions for Node.js and React projects",
+  "prompts": [],
+  "vscodeSettings": {
+    "github.copilot.chat.codeGeneration.useInstructionFiles": true,
+    "chat.promptFiles": true,
+    "typescript.preferences.inlayHints.parameterNames.enabled": "all",
+    "typescript.preferences.inlayHints.variableTypes.enabled": true,
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+      "source.organizeImports": true,
+      "source.fixAll.eslint": true
+    }
+  }
+}

package/templates/typescript/typescript.coding.instructions.md

@@ -0,0 +1,368 @@
+---
+description: 'TypeScript/Node.js coding standards and conventions'
+applyTo: '**/*.ts'
+---
+
+# TypeScript/Node.js Coding Standards
+
+## Language and Framework Preferences
+
+- **Primary Language:** TypeScript for all code files
+- **Code Style:** Follow project's ESLint/Prettier configuration
+- **Target Compatibility:** Node.js 18+, TypeScript 4.9+
+- **Module System:** ES modules (import/export)
+
+## Code Quality Guidelines
+
+- **Type Safety:** Use strict TypeScript configuration with `strict: true`
+- **Type Annotations:** Explicit types for function parameters and return values
+- **Interface Design:** Prefer interfaces over type aliases for object shapes
+- **Generic Constraints:** Use generic constraints to ensure type safety
+- **Null Safety:** Use strict null checks and optional chaining
+
+## Naming Conventions
+
+- **Files:** Use kebab-case for file names (e.g., `user-service.ts`)
+- **Classes:** PascalCase (e.g., `UserService`, `DatabaseConnection`)
+- **Functions/Methods:** camelCase (e.g., `getUserById`, `validateInput`)
+- **Variables:** camelCase (e.g., `userId`, `isValid`)
+- **Constants:** SCREAMING_SNAKE_CASE (e.g., `MAX_RETRY_ATTEMPTS`)
+- **Interfaces:** PascalCase with 'I' prefix (e.g., `IUserRepository`)
+- **Types:** PascalCase (e.g., `UserData`, `ConfigOptions`)
+- **Enums:** PascalCase (e.g., `UserRole`, `HttpStatus`)
+
+## TypeScript-Specific Best Practices
+
+### Type Definitions
+
+```typescript
+// ✅ Good: Explicit interface definitions
+interface UserData {
+  id: string;
+  name: string;
+  email: string;
+  createdAt: Date;
+}
+
+// ✅ Good: Generic constraints
+interface Repository<T extends { id: string }> {
+  findById(id: string): Promise<T | null>;
+  save(entity: T): Promise<T>;
+}
+
+// ❌ Bad: Using 'any' type
+const userData: any = getUserData();
+```
+
+### Error Handling
+
+```typescript
+// ✅ Good: Typed error handling
+class ValidationError extends Error {
+  constructor(
+    message: string,
+    public field: string,
+    public code: string
+  ) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+}
+
+// ✅ Good: Result pattern for error handling
+type Result<T, E = Error> =
+  | { success: true; data: T }
+  | { success: false; error: E };
+
+async function safeOperation(): Promise<Result<UserData>> {
+  try {
+    const data = await fetchUserData();
+    return { success: true, data };
+  } catch (error) {
+    return { success: false, error: error as Error };
+  }
+}
+```
+
+### Async/Await Patterns
+
+```typescript
+// ✅ Good: Proper async/await usage
+async function processUsers(userIds: string[]): Promise<UserData[]> {
+  const users = await Promise.all(
+    userIds.map((id) => userService.findById(id))
+  );
+  return users.filter((user): user is UserData => user !== null);
+}
+
+// ❌ Bad: Mixing promises and async/await
+async function badExample() {
+  return someAsyncOperation().then((result) => {
+    return processResult(result);
+  });
+}
+```
+
+### Module Organization
+
+```typescript
+// ✅ Good: Barrel exports in index.ts
+export { UserService } from './user-service';
+export { DatabaseConnection } from './database-connection';
+export type { UserData, CreateUserRequest } from './types';
+
+// ✅ Good: Single responsibility per file
+// user-service.ts
+export class UserService {
+  constructor(private repository: IUserRepository) {}
+
+  async createUser(data: CreateUserRequest): Promise<UserData> {
+    // Implementation
+  }
+}
+```
+
+## Node.js-Specific Guidelines
+
+### File System Operations
+
+```typescript
+// ✅ Good: Async file operations with proper error handling
+import { promises as fs } from 'fs';
+import { join } from 'path';
+
+async function readConfigFile(
+  filename: string
+): Promise<Record<string, unknown>> {
+  try {
+    const configPath = join(process.cwd(), 'config', filename);
+    const content = await fs.readFile(configPath, 'utf-8');
+    return JSON.parse(content);
+  } catch (error) {
+    throw new Error(`Failed to read config file ${filename}: ${error.message}`);
+  }
+}
+```
+
+### Environment Configuration
+
+```typescript
+// ✅ Good: Type-safe environment variables
+interface EnvironmentConfig {
+  port: number;
+  databaseUrl: string;
+  nodeEnv: 'development' | 'production' | 'test';
+}
+
+function getEnvironmentConfig(): EnvironmentConfig {
+  const port = parseInt(process.env.PORT || '3000', 10);
+  const databaseUrl = process.env.DATABASE_URL;
+  const nodeEnv = process.env.NODE_ENV as EnvironmentConfig['nodeEnv'];
+
+  if (!databaseUrl) {
+    throw new Error('DATABASE_URL environment variable is required');
+  }
+
+  return { port, databaseUrl, nodeEnv: nodeEnv || 'development' };
+}
+```
+
+### Logging and Debugging
+
+```typescript
+// ✅ Good: Structured logging
+interface LogContext {
+  userId?: string;
+  requestId?: string;
+  operation: string;
+}
+
+class Logger {
+  info(message: string, context: LogContext): void {
+    console.log(
+      JSON.stringify({
+        level: 'info',
+        message,
+        timestamp: new Date().toISOString(),
+        ...context,
+      })
+    );
+  }
+
+  error(message: string, error: Error, context: LogContext): void {
+    console.error(
+      JSON.stringify({
+        level: 'error',
+        message,
+        error: error.message,
+        stack: error.stack,
+        timestamp: new Date().toISOString(),
+        ...context,
+      })
+    );
+  }
+}
+```
+
+## Performance Considerations
+
+### Memory Management
+
+```typescript
+// ✅ Good: Streaming large data sets
+import { Transform } from 'stream';
+
+class DataProcessor extends Transform {
+  _transform(
+    chunk: any,
+    encoding: BufferEncoding,
+    callback: TransformCallback
+  ) {
+    // Process chunk by chunk instead of loading everything into memory
+    const processed = this.processChunk(chunk);
+    callback(null, processed);
+  }
+}
+
+// ✅ Good: Cleaning up resources
+class DatabaseConnection {
+  private connection: Connection | null = null;
+
+  async connect(): Promise<void> {
+    this.connection = await createConnection();
+  }
+
+  async disconnect(): Promise<void> {
+    if (this.connection) {
+      await this.connection.close();
+      this.connection = null;
+    }
+  }
+}
+```
+
+### Caching Strategies
+
+```typescript
+// ✅ Good: Simple in-memory cache with TTL
+class CacheService<T> {
+  private cache = new Map<string, { data: T; expires: number }>();
+
+  set(key: string, data: T, ttlMs: number): void {
+    this.cache.set(key, {
+      data,
+      expires: Date.now() + ttlMs,
+    });
+  }
+
+  get(key: string): T | null {
+    const entry = this.cache.get(key);
+    if (!entry || entry.expires < Date.now()) {
+      this.cache.delete(key);
+      return null;
+    }
+    return entry.data;
+  }
+}
+```
+
+## Testing Patterns
+
+### Unit Testing with Jest
+
+```typescript
+// ✅ Good: Type-safe mocking
+interface MockUserRepository extends IUserRepository {
+  findById: jest.MockedFunction<IUserRepository['findById']>;
+  save: jest.MockedFunction<IUserRepository['save']>;
+}
+
+describe('UserService', () => {
+  let userService: UserService;
+  let mockRepository: MockUserRepository;
+
+  beforeEach(() => {
+    mockRepository = {
+      findById: jest.fn(),
+      save: jest.fn(),
+    };
+    userService = new UserService(mockRepository);
+  });
+
+  it('should return user when found', async () => {
+    // Arrange
+    const userData: UserData = {
+      id: '123',
+      name: 'John Doe',
+      email: 'john@example.com',
+      createdAt: new Date(),
+    };
+    mockRepository.findById.mockResolvedValue(userData);
+
+    // Act
+    const result = await userService.getUserById('123');
+
+    // Assert
+    expect(result).toEqual(userData);
+    expect(mockRepository.findById).toHaveBeenCalledWith('123');
+  });
+});
+```
+
+## Security Best Practices
+
+### Input Validation
+
+```typescript
+import { z } from 'zod';
+
+// ✅ Good: Schema-based validation
+const CreateUserSchema = z.object({
+  name: z.string().min(1).max(100),
+  email: z.string().email(),
+  age: z.number().int().min(0).max(150),
+});
+
+type CreateUserRequest = z.infer<typeof CreateUserSchema>;
+
+function validateCreateUserRequest(data: unknown): CreateUserRequest {
+  try {
+    return CreateUserSchema.parse(data);
+  } catch (error) {
+    throw new ValidationError(
+      'Invalid user data',
+      'request',
+      'VALIDATION_FAILED'
+    );
+  }
+}
+```
+
+### SQL Injection Prevention
+
+```typescript
+// ✅ Good: Parameterized queries
+async function getUserByEmail(email: string): Promise<UserData | null> {
+  const query = 'SELECT * FROM users WHERE email = $1';
+  const result = await database.query(query, [email]);
+  return result.rows[0] || null;
+}
+
+// ❌ Bad: String concatenation
+async function badGetUserByEmail(email: string): Promise<UserData | null> {
+  const query = `SELECT * FROM users WHERE email = '${email}'`;
+  const result = await database.query(query);
+  return result.rows[0] || null;
+}
+```
+
+## Common TypeScript Anti-Patterns to Avoid
+
+- **Using `any` type:** Always prefer specific types or `unknown`
+- **Ignoring compiler errors:** Address TypeScript errors, don't suppress them
+- **Overusing `as` assertions:** Use type guards and proper type narrowing
+- **Not defining return types:** Always specify return types for functions
+- **Mixing CommonJS and ES modules:** Stick to ES modules consistently
+- **Not using strict mode:** Always enable strict TypeScript configuration
+- **Mutating props or parameters:** Prefer immutable patterns
+- **Not handling promise rejections:** Always handle async operation failures