chati-dev 1.4.0 → 2.0.2

package/framework/tasks/dev-refactor.md

@@ -0,0 +1,342 @@
+---
+id: dev-refactor
+agent: dev
+trigger: dev-test-write
+phase: build
+requires_input: false
+parallelizable: false
+outputs: [refactored-code]
+handoff_to: dev-debug
+autonomous_gate: true
+criteria:
+  - No code duplication
+  - Functions under 50 lines
+  - Naming is clear
+---
+# Refactor Code
+
+## Purpose
+Improve code quality, readability, and maintainability while preserving functionality, applying DRY, SOLID principles, and project conventions.
+
+## Prerequisites
+- Implementation complete with passing tests
+- Test suite provides safety net
+- Implementation log and test report available
+- Code compiles and lints successfully
+- Understanding of project architecture
+
+## Steps
+
+### 1. Review Current Code State
+Analyze the implementation for refactoring opportunities:
+- Read all newly created files
+- Review modified sections
+- Identify code smells
+- Note complexity hotspots
+- Check for duplication
+
+### 2. Identify Duplication
+Find repeated code patterns:
+- Use Grep to search for similar patterns
+- Look for copy-pasted blocks
+- Find repeated logic
+- Note similar function structures
+- Identify duplicated constants or types
+
+### 3. Extract Common Functions
+Pull out reusable utilities:
+- Create helper functions for repeated logic
+- Move to appropriate utility modules
+- Name functions clearly and descriptively
+- Add proper documentation
+- Ensure single responsibility
+
+Example:
+```typescript
+// Before
+function validateEmail(email: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+}
+
+function validateUsername(username: string): boolean {
+  return /^[a-zA-Z0-9_]{3,20}$/.test(username);
+}
+
+// After - extract to validators.ts
+export const patterns = {
+  email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+  username: /^[a-zA-Z0-9_]{3,20}$/
+};
+
+export function matchesPattern(value: string, pattern: RegExp): boolean {
+  return pattern.test(value);
+}
+```
+
+### 4. Break Down Large Functions
+Split functions exceeding 50 lines:
+- Identify logical sections
+- Extract to named sub-functions
+- Maintain clear data flow
+- Keep functions focused
+- Use descriptive names
+
+### 5. Improve Naming
+Enhance clarity through better names:
+- Replace abbreviations with full words
+- Use domain language
+- Make boolean functions ask questions
+- Use verbs for functions, nouns for classes
+- Be specific and descriptive
+
+Examples:
+- `proc()` → `processPayment()`
+- `data` → `userProfile`
+- `check()` → `isValid()`
+- `handle()` → `handleSubmit()`
+
+### 6. Apply SOLID Principles
+Refactor toward clean architecture:
+
+**Single Responsibility**: Each class/function does one thing
+**Open/Closed**: Open for extension, closed for modification
+**Liskov Substitution**: Subtypes must be substitutable
+**Interface Segregation**: Small, focused interfaces
+**Dependency Inversion**: Depend on abstractions
+
+### 7. Simplify Complex Conditionals
+Make logic easier to understand:
+- Extract conditions to named variables
+- Use early returns to reduce nesting
+- Convert complex if-else to strategy patterns
+- Use guard clauses
+- Simplify boolean expressions
+
+Example:
+```typescript
+// Before
+if (user && user.isActive && user.hasPermission('write') && !user.isBanned) {
+  // do something
+}
+
+// After
+const canWrite = user?.isActive
+  && user?.hasPermission('write')
+  && !user?.isBanned;
+
+if (canWrite) {
+  // do something
+}
+```
+
+### 8. Optimize Data Structures
+Choose appropriate structures:
+- Use Map/Set when appropriate
+- Consider arrays vs objects
+- Use immutable patterns
+- Avoid nested structures
+- Flatten where possible
+
+### 9. Improve Error Handling
+Make errors more robust:
+- Create custom error classes
+- Add error context
+- Use typed errors
+- Centralize error handling
+- Add recovery mechanisms
+
+### 10. Enhance Type Safety
+Strengthen TypeScript usage:
+- Replace `any` with specific types
+- Use union types appropriately
+- Add type guards
+- Use const assertions
+- Leverage utility types
+
+### 11. Add Code Comments
+Document complex logic:
+- Explain "why", not "what"
+- Document assumptions
+- Note edge cases
+- Warn about gotchas
+- Keep comments up to date
+
+### 12. Run Tests Continuously
+Verify refactoring doesn't break functionality:
+- Run test suite after each change
+- Commit working state frequently
+- Use test coverage to find gaps
+- Add tests if coverage drops
+- Verify all acceptance criteria still pass
+
+## Decision Points
+
+### When to Stop Refactoring
+Refactoring is complete when:
+1. No obvious duplication remains
+2. Functions are reasonably sized
+3. Names are clear and consistent
+4. Tests still pass
+5. Code complexity is acceptable
+
+Don't over-optimize or chase perfection.
+
+### When Architecture Needs Changing
+If refactoring reveals architectural issues:
+1. Document the problem
+2. Assess impact of change
+3. Discuss with orchestrator
+4. May need to loop back to architect
+5. Don't make major changes without approval
+
+### When Performance Suffers
+If refactoring impacts performance:
+1. Profile before and after
+2. Identify the bottleneck
+3. Consider optimization
+4. Balance readability vs speed
+5. Document performance decisions
+
+## Error Handling
+
+### Tests Failing After Refactor
+- Identify which tests broke
+- Review changes made
+- Check for logic errors
+- Verify test assumptions still valid
+- Revert if necessary and try smaller changes
+
+### Type Errors After Changes
+- Review type definitions
+- Check generic constraints
+- Verify imports
+- Update type annotations
+- Use type guards where needed
+
+### Lint Violations
+- Run auto-fix: `npm run lint -- --fix`
+- Review remaining issues
+- Update lint rules if too strict
+- Ensure consistency with codebase
+- Don't disable rules without good reason
+
+### Merge Conflicts (if collaborative)
+- Resolve conflicts carefully
+- Run tests after merge
+- Review combined changes
+- Ensure refactoring still makes sense
+- Re-run refactoring if needed
+
+## Output Format
+
+Create `.chati/artifacts/build/refactor-report.yaml`:
+
+```yaml
+task_id: "3.2.1"
+agent: dev
+action: refactor
+timestamp: "2026-02-13T12:00:00Z"
+duration_minutes: 40
+
+files_refactored:
+  - path: "src/modules/chat/chat-service.ts"
+    changes:
+      - "Extracted message validation to validators.ts"
+      - "Split handleMessage into 3 smaller functions"
+      - "Renamed ambiguous variables"
+    lines_before: 156
+    lines_after: 142
+  - path: "src/modules/chat/utils.ts"
+    changes:
+      - "Created utility module for shared functions"
+      - "Moved sanitization logic here"
+    lines_before: 0
+    lines_after: 45
+
+duplication_removed:
+  - description: "Message validation logic"
+    instances: 3
+    extracted_to: "src/modules/chat/validators.ts"
+  - description: "Database error handling"
+    instances: 5
+    extracted_to: "src/lib/db-utils.ts"
+
+functions_split:
+  - original: "ChatService.handleMessage (78 lines)"
+    new_functions:
+      - "validateMessage (15 lines)"
+      - "persistMessage (22 lines)"
+      - "broadcastMessage (18 lines)"
+    rationale: "Separate validation, persistence, and broadcasting concerns"
+
+naming_improvements:
+  - old: "proc"
+    new: "processMessage"
+    file: "chat-service.ts"
+  - old: "data"
+    new: "messageData"
+    file: "chat-service.ts"
+  - old: "check"
+    new: "isValidMessage"
+    file: "validators.ts"
+
+solid_principles_applied:
+  - principle: "Single Responsibility"
+    change: "Split ChatService into ChatService and ChatRepository"
+    rationale: "Separate business logic from data access"
+  - principle: "Dependency Inversion"
+    change: "ChatService now depends on IMessageRepository interface"
+    rationale: "Easier to test and swap implementations"
+
+complexity_reduction:
+  - function: "validateMessage"
+    cyclomatic_complexity_before: 12
+    cyclomatic_complexity_after: 5
+    changes: "Used early returns, extracted conditions"
+
+type_safety_improvements:
+  - change: "Replaced any with MessageData type"
+    file: "chat-service.ts"
+    impact: "Catch type errors at compile time"
+  - change: "Added type guards for message validation"
+    file: "validators.ts"
+    impact: "Runtime type safety"
+
+test_status:
+  all_tests_passing: true
+  coverage_before: 87.5
+  coverage_after: 89.2
+  coverage_change: "+1.7%"
+  tests_added: 2
+  tests_modified: 4
+
+code_quality_metrics:
+  average_function_length: 18
+  max_function_length: 45
+  functions_over_50_lines: 0
+  code_duplication_percentage: 2.3
+  maintainability_index: 82
+
+issues_found:
+  - description: "Message broadcasting could be extracted to separate service"
+    severity: minor
+    plan: "Consider for future iteration"
+  - description: "Error messages could be more specific"
+    severity: minor
+    plan: "Improve in dev-iterate if time permits"
+
+next_steps:
+  - "Run full test suite to verify refactoring"
+  - "Debug any failing tests"
+  - "Prepare for code review"
+```
+
+## Success Criteria
+- All tests still pass
+- No code duplication (or minimal <5%)
+- All functions under 50 lines
+- Variable and function names are clear
+- Cyclomatic complexity is reasonable
+- Code follows SOLID principles
+- Refactor report is complete
+- Coverage maintained or improved

package/framework/tasks/dev-test-write.md

@@ -0,0 +1,306 @@
+---
+id: dev-test-write
+agent: dev
+trigger: dev-implement
+phase: build
+requires_input: false
+parallelizable: true
+outputs: [test-files]
+handoff_to: dev-refactor
+autonomous_gate: true
+criteria:
+  - Tests cover all acceptance criteria
+  - Edge cases tested
+  - Tests pass
+---
+# Write Tests
+
+## Purpose
+Create comprehensive unit and integration tests that verify all acceptance criteria are met and edge cases are handled correctly.
+
+## Prerequisites
+- Implementation complete (dev-implement finished)
+- Implementation log exists at `.chati/artifacts/build/implementation-log.yaml`
+- Test framework configured (Jest, Vitest, or similar)
+- Test utilities and helpers available
+- Source code compiles successfully
+
+## Steps
+
+### 1. Load Implementation Context
+Review the implementation log to understand:
+- Which files were created
+- Which files were modified
+- Acceptance criteria to verify
+- Design decisions that need testing
+- Known technical debt or edge cases
+
+### 2. Analyze Test Requirements
+Map acceptance criteria to test scenarios:
+- Given-When-Then statements become test cases
+- Identify happy path scenarios
+- List error conditions
+- Note boundary conditions
+- Consider race conditions or timing issues
+
+### 3. Set Up Test Structure
+Create test file organization:
+- Name test files: `{module}.test.ts` or `{module}.spec.ts`
+- Mirror source directory structure
+- Set up test suites with `describe` blocks
+- Group related tests logically
+- Use clear, descriptive test names
+
+### 4. Write Unit Tests
+Test individual functions and classes in isolation:
+- Mock external dependencies
+- Test one function per test case
+- Verify return values
+- Check state changes
+- Validate error throwing
+
+Example structure:
+```typescript
+describe('ChatService', () => {
+  describe('sendMessage', () => {
+    it('should persist message to database', async () => {
+      // Arrange
+      const mockDb = createMockDb();
+      const service = new ChatService(mockDb);
+
+      // Act
+      const result = await service.sendMessage({
+        text: 'Hello',
+        userId: '123'
+      });
+
+      // Assert
+      expect(mockDb.insert).toHaveBeenCalledWith(
+        expect.objectContaining({ text: 'Hello' })
+      );
+      expect(result.id).toBeDefined();
+    });
+  });
+});
+```
+
+### 5. Write Integration Tests
+Test components working together:
+- Use real dependencies where possible
+- Test API endpoints end-to-end
+- Verify database interactions
+- Check event propagation
+- Validate state management flows
+
+### 6. Test Edge Cases
+Cover boundary and error conditions:
+- Null or undefined inputs
+- Empty strings or arrays
+- Maximum length inputs
+- Concurrent operations
+- Network failures
+- Database errors
+- Invalid data formats
+
+### 7. Test Error Handling
+Verify error scenarios:
+- Exceptions are thrown correctly
+- Error messages are meaningful
+- Cleanup happens on failure
+- State remains consistent
+- Errors propagate appropriately
+
+### 8. Add Test Utilities
+Create reusable test helpers:
+- Factory functions for test data
+- Mock builders
+- Assertion helpers
+- Setup and teardown utilities
+- Database seeders
+
+### 9. Check Test Coverage
+Verify adequate coverage:
+- Run `npm run test:coverage`
+- Aim for >80% line coverage
+- Ensure all branches tested
+- Cover all acceptance criteria
+- Don't chase 100% blindly
+
+### 10. Optimize Test Performance
+Make tests run efficiently:
+- Avoid unnecessary async operations
+- Use test.concurrent for independent tests
+- Mock expensive operations
+- Clear state between tests
+- Use beforeEach/afterEach wisely
+
+### 11. Document Test Scenarios
+Add clarity to tests:
+- Use descriptive test names
+- Add comments for complex setup
+- Document assumptions
+- Note flaky tests
+- Reference acceptance criteria
+
+### 12. Create Test Report
+Document testing work:
+- List test files created
+- Note coverage metrics
+- Document test strategy
+- Flag areas needing more tests
+- Record any skipped tests
+
+## Decision Points
+
+### When Coverage is Low
+If coverage is below 80%:
+1. Identify untested branches
+2. Prioritize critical paths
+3. Add tests for high-risk areas
+4. Document why some code isn't tested
+5. Plan to add tests in iteration phase
+
+### When Tests are Flaky
+If tests fail intermittently:
+1. Identify timing dependencies
+2. Add proper async handling
+3. Mock time-dependent code
+4. Increase timeouts if needed
+5. Document flaky tests
+
+### When Integration Tests Fail
+If integrated components don't work:
+1. Check component boundaries
+2. Verify API contracts
+3. Review data flow
+4. Add debugging logs
+5. May need to return to implementation
+
+## Error Handling
+
+### Test Framework Issues
+- Verify test framework installed
+- Check configuration files
+- Review import paths
+- Ensure test globals available
+- Check for TypeScript config issues
+
+### Mock Setup Problems
+- Verify mock library imported
+- Check mock syntax
+- Ensure mocks reset between tests
+- Review mock return values
+- Use spy functions for verification
+
+### Async Test Failures
+- Always return promises or use async/await
+- Set appropriate timeouts
+- Handle promise rejections
+- Use waitFor utilities
+- Check for unhandled promise rejections
+
+### Coverage Tool Errors
+- Verify coverage tool configured
+- Check ignore patterns
+- Review threshold settings
+- Ensure source maps generated
+- Check for instrumentation issues
+
+## Output Format
+
+Create `.chati/artifacts/build/test-report.yaml`:
+
+```yaml
+task_id: "3.2.1"
+agent: dev
+action: test-write
+timestamp: "2026-02-13T11:15:00Z"
+duration_minutes: 35
+
+test_files_created:
+  - path: "src/modules/chat/chat-service.test.ts"
+    test_count: 12
+    lines: 245
+  - path: "src/modules/chat/chat-integration.test.ts"
+    test_count: 8
+    lines: 180
+
+test_summary:
+  total_tests: 20
+  passing: 20
+  failing: 0
+  skipped: 0
+  duration_ms: 1847
+
+coverage:
+  statements: 87.5
+  branches: 82.3
+  functions: 91.2
+  lines: 86.8
+  uncovered_files: []
+
+acceptance_criteria_coverage:
+  - id: "AC-1"
+    description: "Chat messages persist to database"
+    tests:
+      - "ChatService.sendMessage should persist message to database"
+      - "ChatService.sendMessage should return saved message with ID"
+    status: fully_covered
+  - id: "AC-2"
+    description: "Real-time updates via WebSocket"
+    tests:
+      - "ChatService should emit message event on send"
+      - "Integration: WebSocket receives new messages"
+    status: fully_covered
+  - id: "AC-3"
+    description: "Message validation and sanitization"
+    tests:
+      - "ChatService should reject empty messages"
+      - "ChatService should sanitize HTML in messages"
+      - "ChatService should validate message length"
+    status: fully_covered
+
+edge_cases_tested:
+  - scenario: "Null or undefined message text"
+    test: "should throw ValidationError for null text"
+  - scenario: "Message exceeding max length"
+    test: "should throw ValidationError for oversized message"
+  - scenario: "Concurrent message sends"
+    test: "should handle concurrent sends without corruption"
+  - scenario: "Database connection lost"
+    test: "should throw DatabaseError on connection failure"
+  - scenario: "WebSocket disconnect during send"
+    test: "should complete send even if broadcast fails"
+
+test_utilities_added:
+  - name: "createMockChatService"
+    purpose: "Factory for test instances"
+  - name: "createTestMessage"
+    purpose: "Generate valid test messages"
+  - name: "seedChatDatabase"
+    purpose: "Populate test database"
+
+areas_needing_attention:
+  - description: "Performance testing for 1000+ messages"
+    reason: "Not covered in unit tests"
+    plan: "Add performance test suite in Phase 4"
+  - description: "WebSocket reconnection scenarios"
+    reason: "Complex to test, low priority"
+    plan: "Add in iteration if time permits"
+
+flaky_tests: []
+
+next_steps:
+  - "Review test coverage with QA perspective"
+  - "Refactor any duplicate test setup code"
+  - "Consider additional edge cases"
+```
+
+## Success Criteria
+- All tests pass
+- Coverage is above 80%
+- All acceptance criteria have corresponding tests
+- Edge cases are tested
+- Error scenarios are covered
+- Test report is complete
+- Tests run in reasonable time (<5s for unit tests)