aigroup-workflow 2.1.2 → 2.2.0

package/skills/test-master/references/testing-anti-patterns.md

@@ -1,231 +0,0 @@
-# Testing Anti-Patterns
-
----
-
-## Core Principle
-
-> **"Test what the code does, not what the mocks do."**
-
-When tests verify mock behavior instead of actual functionality, they provide false confidence while catching zero real bugs.
-
----
-
-## The Five Anti-Patterns
-
-### Anti-Pattern 1: Testing Mock Behavior
-
-**The Problem:** Verifying that mocks exist and were called, rather than testing actual component output.
-
-```typescript
-// ❌ BAD: Testing the mock, not the behavior
-it('should call the API', () => {
-  const mockApi = jest.fn().mockResolvedValue({ data: 'test' });
-  const service = new UserService(mockApi);
-
-  service.getUser(1);
-
-  expect(mockApi).toHaveBeenCalledWith(1); // Testing mock, not result
-});
-```
-
-```typescript
-// ✅ GOOD: Testing actual behavior
-it('should return user data from API', async () => {
-  const mockApi = jest.fn().mockResolvedValue({ id: 1, name: 'Alice' });
-  const service = new UserService(mockApi);
-
-  const user = await service.getUser(1);
-
-  expect(user.name).toBe('Alice'); // Testing actual output
-});
-```
-
-**Solution:** Test the genuine component output. If you can only verify mock calls, reconsider whether the test adds value.
-
----
-
-### Anti-Pattern 2: Test-Only Methods in Production
-
-**The Problem:** Adding methods to production classes solely for test setup or cleanup.
-
-```typescript
-// ❌ BAD: Production code polluted with test concerns
-class UserCache {
-  private cache: Map<number, User> = new Map();
-
-  getUser(id: number): User | undefined {
-    return this.cache.get(id);
-  }
-
-  // This method exists ONLY for tests
-  _resetForTesting(): void {
-    this.cache.clear();
-  }
-}
-```
-
-```typescript
-// ✅ GOOD: Test utilities separate from production
-// production/UserCache.ts
-class UserCache {
-  private cache: Map<number, User> = new Map();
-
-  getUser(id: number): User | undefined {
-    return this.cache.get(id);
-  }
-}
-
-// test/helpers.ts
-function createFreshCache(): UserCache {
-  return new UserCache(); // Fresh instance per test
-}
-```
-
-**Solution:** Relocate cleanup logic to test utility functions. Use fresh instances per test instead of reset methods.
-
----
-
-### Anti-Pattern 3: Mocking Without Understanding
-
-**The Problem:** Over-mocking without grasping side effects, leading to tests that pass but hide real issues.
-
-```typescript
-// ❌ BAD: Mocking everything without understanding
-it('should process order', async () => {
-  jest.mock('./inventory');
-  jest.mock('./payment');
-  jest.mock('./shipping');
-  jest.mock('./notifications');
-
-  const result = await processOrder(order);
-
-  expect(result.success).toBe(true); // What did we actually test?
-});
-```
-
-```typescript
-// ✅ GOOD: Strategic mocking with real components where possible
-it('should process order with real inventory check', async () => {
-  // Real inventory service against test database
-  const inventory = new InventoryService(testDb);
-
-  // Mock only external services
-  const payment = mockPaymentGateway();
-
-  const processor = new OrderProcessor(inventory, payment);
-  const result = await processor.process(order);
-
-  expect(result.success).toBe(true);
-  expect(await inventory.getStock(order.itemId)).toBe(originalStock - 1);
-});
-```
-
-**Solution:** Run tests with real implementations first to understand behavior. Then mock at the appropriate level - external services, not internal logic.
-
----
-
-### Anti-Pattern 4: Incomplete Mocks
-
-**The Problem:** Partial mock responses missing downstream fields that production code expects.
-
-```typescript
-// ❌ BAD: Incomplete mock response
-const mockUserApi = jest.fn().mockResolvedValue({
-  id: 1,
-  name: 'Test User'
-  // Missing: email, createdAt, permissions, settings...
-});
-
-// Test passes, but production crashes when accessing user.email
-```
-
-```typescript
-// ✅ GOOD: Complete mock matching real API response
-const mockUserApi = jest.fn().mockResolvedValue({
-  id: 1,
-  name: 'Test User',
-  email: 'test@example.com',
-  createdAt: '2024-01-01T00:00:00Z',
-  permissions: ['read', 'write'],
-  settings: {
-    theme: 'light',
-    notifications: true
-  }
-});
-
-// Or use a factory
-const mockUserApi = jest.fn().mockResolvedValue(
-  createMockUser({ name: 'Test User' }) // Factory fills defaults
-);
-```
-
-**Solution:** Mirror complete real API response structure. Use factories to generate complete mock objects with sensible defaults.
-
----
-
-### Anti-Pattern 5: Integration Tests as Afterthought
-
-**The Problem:** Treating testing as optional follow-up work rather than integral to development.
-
-```typescript
-// ❌ BAD: "We'll add tests later"
-// Day 1: Write 500 lines of code
-// Day 2: Write 500 more lines
-// Day 3: "We need to ship, tests can wait"
-// Day 30: Catastrophic bug in production
-// Day 31: "Why didn't we have tests?"
-```
-
-```typescript
-// ✅ GOOD: Tests are part of implementation
-// Write failing test
-it('should reject duplicate usernames', async () => {
-  await createUser({ username: 'alice' });
-
-  await expect(createUser({ username: 'alice' }))
-    .rejects.toThrow('Username already exists');
-});
-
-// Make it pass
-async function createUser(data: UserInput): Promise<User> {
-  const existing = await db.users.findByUsername(data.username);
-  if (existing) {
-    throw new Error('Username already exists');
-  }
-  return db.users.create(data);
-}
-
-// Feature AND test ship together
-```
-
-**Solution:** Follow TDD - testing is implementation, not documentation. No feature is "done" without tests.
-
----
-
-## Detection Checklist
-
-Review your tests for these warning signs:
-
-| Warning Sign | Anti-Pattern |
-|-------------|--------------|
-| `expect(mock).toHaveBeenCalled()` without testing output | Testing mock behavior |
-| Methods starting with `_` or `ForTesting` in production | Test-only methods |
-| Every dependency is mocked | Mocking without understanding |
-| Mocks return `{ success: true }` only | Incomplete mocks |
-| Test files added weeks after feature ships | Tests as afterthought |
-
----
-
-## Quick Reference
-
-| Anti-Pattern | Symptom | Fix |
-|-------------|---------|-----|
-| Testing mocks | Only mock assertions, no behavior tests | Assert on actual output |
-| Test-only methods | `_reset()`, `_setForTest()` in prod | Use fresh instances |
-| Over-mocking | 10+ mocks per test | Test with real deps first |
-| Incomplete mocks | Minimal stub responses | Use factories, match reality |
-| Tests as afterthought | Features ship untested | TDD from the start |
-
----
-
-*Content adapted from [obra/superpowers](https://github.com/obra/superpowers) by Jesse Vincent (@obra), MIT License.*

package/skills/test-master/references/unit-testing.md

@@ -1,113 +0,0 @@
-# Unit Testing
-
-## Jest/Vitest Pattern
-
-```typescript
-describe('UserService', () => {
-  let service: UserService;
-  let mockRepo: jest.Mocked<UserRepository>;
-
-  beforeEach(() => {
-    mockRepo = { findById: jest.fn(), save: jest.fn() } as any;
-    service = new UserService(mockRepo);
-  });
-
-  afterEach(() => jest.clearAllMocks());
-
-  describe('getUser', () => {
-    it('returns user when found', async () => {
-      const user = { id: '1', name: 'Test' };
-      mockRepo.findById.mockResolvedValue(user);
-
-      const result = await service.getUser('1');
-
-      expect(result).toEqual(user);
-      expect(mockRepo.findById).toHaveBeenCalledWith('1');
-    });
-
-    it('throws NotFoundError when user not found', async () => {
-      mockRepo.findById.mockResolvedValue(null);
-
-      await expect(service.getUser('1')).rejects.toThrow(NotFoundError);
-    });
-  });
-});
-```
-
-## pytest Pattern
-
-```python
-import pytest
-from unittest.mock import Mock, AsyncMock
-
-class TestUserService:
-    @pytest.fixture
-    def mock_repo(self):
-        return Mock()
-
-    @pytest.fixture
-    def service(self, mock_repo):
-        return UserService(mock_repo)
-
-    async def test_get_user_returns_user(self, service, mock_repo):
-        mock_repo.find_by_id = AsyncMock(return_value={"id": "1", "name": "Test"})
-
-        result = await service.get_user("1")
-
-        assert result == {"id": "1", "name": "Test"}
-        mock_repo.find_by_id.assert_called_once_with("1")
-
-    async def test_get_user_raises_not_found(self, service, mock_repo):
-        mock_repo.find_by_id = AsyncMock(return_value=None)
-
-        with pytest.raises(NotFoundError):
-            await service.get_user("1")
-```
-
-## Mocking Patterns
-
-```typescript
-// Mock functions
-const mockFn = jest.fn();
-mockFn.mockReturnValue('value');
-mockFn.mockResolvedValue('async value');
-mockFn.mockRejectedValue(new Error('error'));
-
-// Mock modules
-jest.mock('./database', () => ({
-  query: jest.fn(),
-}));
-
-// Spy on existing methods
-jest.spyOn(console, 'log').mockImplementation(() => {});
-```
-
-## Test Organization
-
-```typescript
-describe('Feature', () => {
-  describe('happy path', () => {
-    it('does expected behavior', () => {});
-  });
-
-  describe('edge cases', () => {
-    it('handles empty input', () => {});
-    it('handles max values', () => {});
-  });
-
-  describe('error cases', () => {
-    it('throws on invalid input', () => {});
-  });
-});
-```
-
-## Quick Reference
-
-| Pattern | Use Case |
-|---------|----------|
-| `describe()` | Group related tests |
-| `it()` / `test()` | Single test case |
-| `beforeEach()` | Setup before each test |
-| `jest.fn()` | Create mock function |
-| `mockResolvedValue()` | Mock async return |
-| `expect().toThrow()` | Assert exception |

package/skills/typescript-pro/SKILL.md

@@ -1,145 +0,0 @@
----
-name: typescript-pro
-description: Implements advanced TypeScript type systems, creates custom type guards, utility types, and branded types, and configures tRPC for end-to-end type safety. Use when building TypeScript applications requiring advanced generics, conditional or mapped types, discriminated unions, monorepo setup, or full-stack type safety with tRPC.
-license: MIT
-metadata:
-  author: https://github.com/Jeffallan
-  version: "1.1.0"
-  domain: language
-  triggers: TypeScript, generics, type safety, conditional types, mapped types, tRPC, tsconfig, type guards, discriminated unions
-  role: specialist
-  scope: implementation
-  output-format: code
-  related-skills: fullstack-guardian, api-designer
----
-
-# TypeScript Pro
-
-## Core Workflow
-
-1. **Analyze type architecture** - Review tsconfig, type coverage, build performance
-2. **Design type-first APIs** - Create branded types, generics, utility types
-3. **Implement with type safety** - Write type guards, discriminated unions, conditional types; run `tsc --noEmit` to catch type errors before proceeding
-4. **Optimize build** - Configure project references, incremental compilation, tree shaking; re-run `tsc --noEmit` to confirm zero errors after changes
-5. **Test types** - Confirm type coverage with a tool like `type-coverage`; validate that all public APIs have explicit return types; iterate on steps 3–4 until all checks pass
-
-## Reference Guide
-
-Load detailed guidance based on context:
-
-| Topic | Reference | Load When |
-|-------|-----------|-----------|
-| Advanced Types | `references/advanced-types.md` | Generics, conditional types, mapped types, template literals |
-| Type Guards | `references/type-guards.md` | Type narrowing, discriminated unions, assertion functions |
-| Utility Types | `references/utility-types.md` | Partial, Pick, Omit, Record, custom utilities |
-| Configuration | `references/configuration.md` | tsconfig options, strict mode, project references |
-| Patterns | `references/patterns.md` | Builder pattern, factory pattern, type-safe APIs |
-
-## Code Examples
-
-### Branded Types
-```typescript
-// Branded type for domain modeling
-type Brand<T, B extends string> = T & { readonly __brand: B };
-type UserId  = Brand<string, "UserId">;
-type OrderId = Brand<number, "OrderId">;
-
-const toUserId  = (id: string): UserId  => id as UserId;
-const toOrderId = (id: number): OrderId => id as OrderId;
-
-// Usage — prevents accidental id mix-ups at compile time
-function getOrder(userId: UserId, orderId: OrderId) { /* ... */ }
-```
-
-### Discriminated Unions & Type Guards
-```typescript
-type LoadingState = { status: "loading" };
-type SuccessState = { status: "success"; data: string[] };
-type ErrorState   = { status: "error";   error: Error };
-type RequestState = LoadingState | SuccessState | ErrorState;
-
-// Type predicate guard
-function isSuccess(state: RequestState): state is SuccessState {
-  return state.status === "success";
-}
-
-// Exhaustive switch with discriminated union
-function renderState(state: RequestState): string {
-  switch (state.status) {
-    case "loading": return "Loading…";
-    case "success": return state.data.join(", ");
-    case "error":   return state.error.message;
-    default: {
-      const _exhaustive: never = state;
-      throw new Error(`Unhandled state: ${_exhaustive}`);
-    }
-  }
-}
-```
-
-### Custom Utility Types
-```typescript
-// Deep readonly — immutable nested objects
-type DeepReadonly<T> = {
-  readonly [K in keyof T]: T[K] extends object ? DeepReadonly<T[K]> : T[K];
-};
-
-// Require exactly one of a set of keys
-type RequireExactlyOne<T, Keys extends keyof T = keyof T> =
-  Pick<T, Exclude<keyof T, Keys>> &
-  { [K in Keys]-?: Required<Pick<T, K>> & Partial<Record<Exclude<Keys, K>, never>> }[Keys];
-```
-
-### Recommended tsconfig.json
-```json
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "strict": true,
-    "noUncheckedIndexedAccess": true,
-    "noImplicitOverride": true,
-    "exactOptionalPropertyTypes": true,
-    "isolatedModules": true,
-    "declaration": true,
-    "declarationMap": true,
-    "incremental": true,
-    "skipLibCheck": false
-  }
-}
-```
-
-## Constraints
-
-### MUST DO
-- Enable strict mode with all compiler flags
-- Use type-first API design
-- Implement branded types for domain modeling
-- Use `satisfies` operator for type validation
-- Create discriminated unions for state machines
-- Use `Annotated` pattern with type predicates
-- Generate declaration files for libraries
-- Optimize for type inference
-
-### MUST NOT DO
-- Use explicit `any` without justification
-- Skip type coverage for public APIs
-- Mix type-only and value imports
-- Disable strict null checks
-- Use `as` assertions without necessity
-- Ignore compiler performance warnings
-- Skip declaration file generation
-- Use enums (prefer const objects with `as const`)
-
-## Output Templates
-
-When implementing TypeScript features, provide:
-1. Type definitions (interfaces, types, generics)
-2. Implementation with type guards
-3. tsconfig configuration if needed
-4. Brief explanation of type design decisions
-
-## Knowledge Reference
-
-TypeScript 5.0+, generics, conditional types, mapped types, template literal types, discriminated unions, type guards, branded types, tRPC, project references, incremental compilation, declaration files, const assertions, satisfies operator