@sun-asterisk/impact-analyzer 1.0.3 → 1.0.5

package/.specify/tasks/task-002-database-detector.md

@@ -0,0 +1,593 @@
+# Task 002: Database Impact Detector - Spec-Driven Implementation
+
+**Status:** 📋 TODO  
+**Priority:** 🔴 HIGH  
+**Assignee:** AI Agent  
+**Created:** 2025-12-25
+
+---
+
+## 📝 Overview
+
+Implement a **spec-driven database impact detector** that identifies affected database tables and operations from code changes. This task focuses on **table change detection** using the existing specification as the single source of truth.
+
+## 🎯 What is Spec-Driven Development?
+
+**Spec-Driven Development (SDD)** is a methodology where:
+
+1. **Specification First** - Write detailed functional requirements BEFORE coding
+2. **Spec as Contract** - The spec defines expected behavior, inputs, outputs
+3. **Code Follows Spec** - Implementation must match spec exactly
+4. **Spec as Test Oracle** - Verification checks if code meets spec requirements
+
+### Why Spec-Driven?
+
+✅ **Clarity** - Everyone knows what to build  
+✅ **Quality** - Requirements are clear before coding  
+✅ **Testability** - Spec defines expected outputs  
+✅ **Maintainability** - Spec documents intent  
+✅ **AI-Friendly** - LLMs can generate code from clear specs  
+
+### SDD Workflow
+
+```
+┌─────────────────┐
+│  1. Read Spec   │ ← Start here
+└────────┬────────┘
+         ↓
+┌─────────────────┐
+│ 2. Understand   │ ← What's required?
+│    Requirements │
+└────────┬────────┘
+         ↓
+┌─────────────────┐
+│ 3. Design Code  │ ← Plan implementation
+│    Structure    │
+└────────┬────────┘
+         ↓
+┌─────────────────┐
+│ 4. Implement    │ ← Code according to spec
+│    Features     │
+└────────┬────────┘
+         ↓
+┌─────────────────┐
+│ 5. Verify       │ ← Check against spec
+│    Against Spec │
+└────────┬────────┘
+         ↓
+┌─────────────────┐
+│ 6. Update Spec  │ ← If requirements change
+│    if Needed    │
+└─────────────────┘
+```
+
+## 📚 Reference Specification
+
+**Location:** `.specify/specs/features/database-impact-detection.md`
+
+**Key Requirements from Spec:**
+
+| Requirement | Description | Priority |
+|------------|-------------|----------|
+| **FR-001** | Detect Entity/Model Changes | CRITICAL |
+| **FR-002** | Extract Table Names | CRITICAL |
+| **FR-003** | Detect Repository/DAO Changes | HIGH |
+| **FR-004** | Classify Impact Type | HIGH |
+| **FR-005** | Identify CRUD Operations | MEDIUM |
+| **FR-006** | Generate Database Report | CRITICAL |
+
+## 🎯 Goals - Table Change Detection Focus
+
+### Primary Goal
+**Detect which database tables are affected when code changes occur**
+
+### Specific Detection Targets
+
+1. **Entity Definition Changes** (FR-001)
+   - New columns added to entity
+   - Existing columns modified
+   - Relations added/removed
+   - Entity class renamed
+
+2. **Table Name Identification** (FR-002)
+   - Extract from `@Entity('table_name')`
+   - Extract from `@Entity({ name: 'table_name' })`
+   - Convert class name to snake_case if not specified
+
+3. **Repository Method Changes** (FR-003)
+   - Changes in repository files
+   - Changes in methods that call repository
+   - Track call chain: Service → Repository → Table
+
+4. **Operation Detection** (FR-005)
+   - Identify INSERT operations (save, create, insert)
+   - Identify UPDATE operations (update, merge)
+   - Identify DELETE operations (delete, remove, softDelete)
+   - Identify SELECT operations (find, findOne, findBy)
+
+## 📋 Implementation Tasks
+
+### Phase 1: Spec Analysis ✅
+
+- [x] Read database impact detection spec
+- [x] Understand all functional requirements
+- [x] Identify output schema requirements
+- [x] List all ORM patterns to support (TypeORM, Sequelize)
+
+### Phase 2: Current Implementation Review
+
+- [ ] Audit existing `core/detectors/database-detector.js`
+- [ ] List what's already implemented
+- [ ] Identify gaps vs. specification
+- [ ] Document what needs to be added/changed
+
+**Audit Checklist:**
+```javascript
+// Check if current code implements:
+✓ Entity change detection
+✓ Table name extraction
+✓ Repository method tracking
+✓ CRUD operation identification
+? Output matches spec schema
+? Severity classification
+? All ORM patterns supported
+```
+
+### Phase 3: Implement Table Detection (Core Feature)
+
+#### 3.1 Entity Change Detection
+
+**Spec Requirement:** FR-001
+
+**Implementation:**
+```javascript
+/**
+ * Detect changes to entity/model files
+ * @param {ChangedFile[]} changedFiles
+ * @returns {EntityChange[]}
+ */
+detectEntityChanges(changedFiles) {
+  const entityChanges = [];
+  
+  for (const file of changedFiles) {
+    // Check if file is an entity
+    if (this.isEntityFile(file)) {
+      const change = this.analyzeEntityChange(file);
+      entityChanges.push(change);
+    }
+  }
+  
+  return entityChanges;
+}
+
+isEntityFile(file) {
+  // Check for:
+  // - @Entity() decorator
+  // - extends Model
+  // - .entity.ts extension
+  // - /entities/ in path
+}
+```
+
+**Acceptance Criteria:**
+- [ ] Detects TypeORM entities with @Entity decorator
+- [ ] Detects Sequelize models with @Table decorator
+- [ ] Identifies entity files by naming convention
+- [ ] Extracts changed properties/columns
+
+#### 3.2 Table Name Extraction
+
+**Spec Requirement:** FR-002
+
+**Implementation:**
+```javascript
+/**
+ * Extract database table name from entity
+ * @param {string} entityCode - Entity class code
+ * @param {string} className - Entity class name
+ * @returns {string} Table name in snake_case
+ */
+extractTableName(entityCode, className) {
+  // Priority order:
+  // 1. Explicit: @Entity('users')
+  // 2. Options: @Entity({ name: 'users' })
+  // 3. Convert className to snake_case
+  
+  const explicitMatch = entityCode.match(/@Entity\s*\(\s*['"](\w+)['"]/);
+  if (explicitMatch) return explicitMatch[1];
+  
+  const optionsMatch = entityCode.match(/@Entity\s*\(\s*\{.*name:\s*['"](\w+)['"]/);
+  if (optionsMatch) return optionsMatch[1];
+  
+  return this.classNameToTableName(className);
+}
+
+classNameToTableName(className) {
+  // Convert: UserProfile → user_profile
+  return className
+    .replace(/Entity$/, '')  // Remove "Entity" suffix
+    .replace(/([A-Z])/g, '_$1')  // Add underscore before capitals
+    .toLowerCase()
+    .replace(/^_/, '');  // Remove leading underscore
+}
+```
+
+**Acceptance Criteria:**
+- [ ] Extracts explicit table names from @Entity('name')
+- [ ] Extracts from @Entity({ name: 'name' })
+- [ ] Converts class names correctly: UserProfile → user_profile
+- [ ] Handles Entity suffix removal
+
+#### 3.3 Repository Method Detection
+
+**Spec Requirement:** FR-003
+
+**Implementation:**
+```javascript
+/**
+ * Find repository methods affected by changes
+ * Uses method call graph to trace: Change → Service → Repository
+ * @param {MethodChange[]} changedMethods
+ * @returns {RepositoryMethod[]}
+ */
+findAffectedRepositoryMethods(changedMethods) {
+  const repoMethods = [];
+  const visited = new Set();
+  
+  for (const method of changedMethods) {
+    // Traverse call graph upward
+    const repos = this.traceToRepository(method, visited);
+    repoMethods.push(...repos);
+  }
+  
+  return this.deduplicateRepositoryMethods(repoMethods);
+}
+
+traceToRepository(method, visited, depth = 0) {
+  if (depth > 10 || visited.has(method.key)) return [];
+  visited.add(method.key);
+  
+  // Check if this is a repository
+  if (this.isRepositoryMethod(method)) {
+    return [method];
+  }
+  
+  // Get callers and continue tracing
+  const callers = this.methodCallGraph.getCallers(method);
+  const repos = [];
+  
+  for (const caller of callers) {
+    repos.push(...this.traceToRepository(caller, visited, depth + 1));
+  }
+  
+  return repos;
+}
+
+isRepositoryMethod(method) {
+  return (
+    method.file?.includes('/repository/') ||
+    method.file?.includes('.repository.') ||
+    method.className?.includes('Repository')
+  );
+}
+```
+
+**Acceptance Criteria:**
+- [ ] Traces changes to repository methods
+- [ ] Handles deep call chains (Service → Service → Repository)
+- [ ] Prevents infinite loops with visited tracking
+- [ ] Identifies repository by file path and class name
+
+#### 3.4 CRUD Operation Detection
+
+**Spec Requirement:** FR-005
+
+**Implementation:**
+```javascript
+/**
+ * Identify database operations from code changes
+ * @param {string} diff - Git diff of changed code
+ * @returns {DbOperation[]}
+ */
+detectOperations(diff) {
+  const operations = [];
+  
+  // TypeORM operation patterns
+  const operationMap = {
+    'insert': 'INSERT',
+    'save': 'INSERT/UPDATE',
+    'create': 'INSERT',
+    'update': 'UPDATE',
+    'merge': 'UPDATE',
+    'delete': 'DELETE',
+    'remove': 'DELETE',
+    'softDelete': 'SOFT_DELETE',
+    'find': 'SELECT',
+    'findOne': 'SELECT',
+    'findBy': 'SELECT',
+  };
+  
+  // Scan added lines for operations
+  const addedLines = this.extractAddedLines(diff);
+  
+  for (const line of addedLines) {
+    for (const [method, opType] of Object.entries(operationMap)) {
+      if (line.includes(`.${method}(`)) {
+        operations.push({
+          type: opType,
+          method: method,
+          line: line.trim()
+        });
+      }
+    }
+  }
+  
+  return operations;
+}
+```
+
+**Acceptance Criteria:**
+- [ ] Detects INSERT operations (save, create, insert)
+- [ ] Detects UPDATE operations (update, merge)
+- [ ] Detects DELETE operations (delete, remove)
+- [ ] Detects SELECT operations (find, findOne)
+- [ ] Only analyzes added lines (+) in diff
+
+### Phase 4: Output Format (Match Spec)
+
+**Spec Requirement:** FR-006
+
+**Required Output Schema:**
+```javascript
+{
+  tableName: string,      // snake_case table name
+  modelName: string,      // Entity class name
+  modelPath: string,      // File path to entity
+  impactType: 'schema' | 'query' | 'relation' | 'migration',
+  operations: ('SELECT'|'INSERT'|'UPDATE'|'DELETE')[],
+  changeSource: FileChange,
+  severity: 'low' | 'medium' | 'high' | 'critical'
+}
+```
+
+**Implementation:**
+```javascript
+/**
+ * Format database impact according to spec
+ * @param {Object} databaseChanges - Raw detected changes
+ * @returns {DatabaseImpact[]} - Spec-compliant output
+ */
+formatDatabaseImpact(databaseChanges) {
+  const impacts = [];
+  
+  for (const table of databaseChanges.tables) {
+    impacts.push({
+      tableName: table.name,
+      modelName: table.entity,
+      modelPath: table.file,
+      impactType: this.classifyImpactType(table),
+      operations: Array.from(table.operations),
+      changeSource: table.changeSource,
+      severity: this.calculateSeverity(table)
+    });
+  }
+  
+  return impacts;
+}
+
+classifyImpactType(table) {
+  // Schema: entity file changed
+  if (table.isEntityFile) return 'schema';
+  
+  // Relation: relation decorators changed
+  if (table.hasRelationChange) return 'relation';
+  
+  // Migration: migration file changed
+  if (table.isMigrationFile) return 'migration';
+  
+  // Query: repository changed
+  return 'query';
+}
+
+calculateSeverity(table) {
+  // Per spec: Section 6
+  if (table.impactType === 'schema') return 'critical';
+  if (table.impactType === 'relation') return 'high';
+  if (table.operations.includes('DELETE')) return 'high';
+  if (table.operations.includes('UPDATE')) return 'medium';
+  if (table.operations.includes('INSERT')) return 'medium';
+  return 'low';  // SELECT only
+}
+```
+
+**Acceptance Criteria:**
+- [ ] Output matches spec schema exactly
+- [ ] All required fields present
+- [ ] Severity follows spec rules
+- [ ] Impact type classification correct
+
+### Phase 5: Logging & Verbose Mode
+
+**Apply same pattern as Task 001:**
+
+```javascript
+import { createLogger } from '../utils/logger.js';
+
+export class DatabaseDetector {
+  constructor(methodCallGraph, config) {
+    this.methodCallGraph = methodCallGraph;
+    this.config = config;
+    this.logger = createLogger(config.verbose);
+  }
+  
+  async detect(changedFiles) {
+    this.logger.info('🔍 Analyzing database impacts...');
+    this.logger.verbose('DatabaseDetector', `Processing ${changedFiles.length} files`);
+    
+    const startTime = Date.now();
+    
+    // ... detection logic
+    
+    const duration = Date.now() - startTime;
+    this.logger.verbose('DatabaseDetector', `Completed in ${duration}ms`);
+    
+    return impacts;
+  }
+}
+```
+
+**Acceptance Criteria:**
+- [ ] Normal mode: clean output only
+- [ ] Verbose mode: detailed tracing with [DatabaseDetector] prefix
+- [ ] Performance timing shown in verbose mode
+
+## ✅ Verification Against Spec
+
+### Checklist
+
+Compare implementation against spec requirements:
+
+**Functional Requirements:**
+- [ ] FR-001: Entity/Model changes detected ✓
+- [ ] FR-002: Table names extracted correctly ✓
+- [ ] FR-003: Repository changes tracked ✓
+- [ ] FR-004: Impact type classified ✓
+- [ ] FR-005: CRUD operations identified ✓
+- [ ] FR-006: Report format matches spec ✓
+
+**Output Schema:**
+- [ ] `tableName` field present and correct
+- [ ] `modelName` field present
+- [ ] `modelPath` field present
+- [ ] `impactType` enum matches spec
+- [ ] `operations` array present
+- [ ] `severity` classification correct
+
+**ORM Support:**
+- [ ] TypeORM @Entity detection
+- [ ] TypeORM @Column detection
+- [ ] Repository pattern detection
+- [ ] Method call tracing
+
+## 🧪 Testing
+
+### Manual Test Cases
+
+**Test 1: Entity Column Change**
+```bash
+# Modify an entity column
+echo "Test scenario from spec Section 8"
+
+# Expected: 
+# - tableName: "users"
+# - impactType: "schema"
+# - severity: "critical"
+```
+
+**Test 2: Repository Method Change**
+```bash
+# Modify a repository method
+
+# Expected:
+# - tableName: extracted from repository
+# - impactType: "query"
+# - operations: detected from method
+```
+
+**Test 3: Service Change Affecting Database**
+```bash
+# Change a service that calls repository
+
+# Expected:
+# - Call graph traced to repository
+# - Table identified
+# - Operations detected
+```
+
+### Verbose Mode Test
+```bash
+node cli.js --input=src --base=origin/main --verbose
+```
+
+**Expected Output:**
+```
+🔍 Step 2: Analyzing impact...
+[DatabaseDetector] Processing 3 files
+[DatabaseDetector] Analyzing entity: UserEntity
+[DatabaseDetector] Extracted table name: users
+[DatabaseDetector] Detected operations: INSERT, UPDATE
+[DatabaseDetector] Tracing call chain: UserService → UserRepository
+[DatabaseDetector] Completed in 85ms
+
+📊 Database Impact:
+   ✓ Affected tables: 2
+   • users (schema change, critical)
+   • posts (query change, medium)
+```
+
+## 📊 Success Metrics
+
+- [ ] Detects >95% of entity changes (per NFR-002)
+- [ ] Detects >85% of repository changes (per NFR-002)
+- [ ] Analysis time <5 seconds (per NFR-001)
+- [ ] Zero crashes on valid code
+- [ ] Output validates against spec schema
+
+## 🔗 References
+
+- **Spec**: `.specify/specs/features/database-impact-detection.md`
+- **Current Code**: `core/detectors/database-detector.js`
+- **Task 001**: `.specify/tasks/task-001-refactor-api-detector.md`
+- **Logger Pattern**: `core/utils/logger.js`
+- **Code Rules**: `.github/copilot-instructions.md`
+
+## 📝 Notes
+
+### Spec-Driven Best Practices
+
+1. **Read spec first, code second** - Always check spec before coding
+2. **Question discrepancies** - If code doesn't match spec, ask why
+3. **Update spec if requirements change** - Keep spec as source of truth
+4. **Use spec for testing** - Test cases come from spec examples
+5. **Reference spec in code comments** - Link requirements to implementation
+
+### Table Detection Strategy
+
+```
+┌─────────────────┐
+│  Changed File   │
+└────────┬────────┘
+         ↓
+    ┌────────────┐
+    │ Is Entity? │──Yes──> Extract table name → Return
+    └─────┬──────┘
+          │ No
+          ↓
+    ┌──────────────────┐
+    │ Has DB calls in  │──Yes──> Extract operations → Return
+    │ changed lines?   │
+    └─────┬────────────┘
+          │ No
+          ↓
+    ┌──────────────────┐
+    │ Trace call graph │──Repo found──> Extract table → Return
+    │ to repository    │
+    └──────────────────┘
+```
+
+## 🎯 Definition of Done
+
+- [ ] All Phase 2-5 tasks completed
+- [ ] Code matches spec requirements exactly
+- [ ] Output schema matches spec
+- [ ] Verbose mode implemented
+- [ ] Manual tests pass
+- [ ] Performance targets met
+- [ ] Documentation updated
+- [ ] Code reviewed for compliance with code rules
+
+---
+
+**Last Updated:** 2025-12-25  
+**Spec Version:** 1.0  
+**Implementation Status:** TODO