@sun-asterisk/impact-analyzer 1.0.3 → 1.0.5

package/.specify/tasks/task-001-refactor-api-detector.md

@@ -0,0 +1,284 @@
+# Task 001: Refactor API Detector for Performance & Simplicity
+
+**Status:** 📋 TODO  
+**Priority:** 🔴 HIGH  
+**Assignee:** AI Agent  
+**Created:** 2025-12-25
+
+---
+
+## 📝 Overview
+
+Refactor API detector to use `core/` folder structure, optimize performance, remove unused code, and improve logging with verbose mode.
+
+## 🎯 Goals
+
+1. **Migrate from `modules/` to `core/`** - Use consistent folder structure
+2. **Optimize Performance** - Remove unused functions, improve call graph traversal
+3. **Simplify Documentation** - Clear docs for AI code generation
+4. **Improve Logging** - Add verbose mode with clear, contextual logs
+
+## 📋 Tasks
+
+### 1. Folder Structure Migration
+
+**Current (if using modules):**
+```
+modules/
+├── api-detector.js
+├── call-graph-builder.js
+└── utils.js
+```
+
+**Target:**
+```
+core/
+├── detectors/
+│   └── endpoint-detector.js    # API impact detection
+└── utils/
+    ├── method-call-graph.js    # Call graph building
+    └── ast-parser.js           # AST parsing utilities
+```
+
+**Action Items:**
+- [ ] Move API detector logic to `core/detectors/endpoint-detector.js`
+- [ ] Move call graph logic to `core/utils/method-call-graph.js`
+- [ ] Update all imports to reference new paths
+- [ ] Remove old `modules/` folder references
+
+### 2. Performance Optimization
+
+**Remove Unused Functions:**
+- [ ] Audit all exported functions - remove if not called
+- [ ] Remove debug functions not used in production
+- [ ] Remove duplicate utility functions
+- [ ] Consolidate similar AST traversal logic
+
+**Optimize Call Graph Traversal:**
+- [ ] Use Set for visited nodes (avoid array lookups)
+- [ ] Add max depth limit (default: 10 levels)
+- [ ] Early return when endpoint found
+- [ ] Cache decorator lookups per method
+
+**Example Optimization:**
+```javascript
+// Before: Array lookup O(n)
+if (visited.includes(method)) return;
+
+// After: Set lookup O(1)
+if (visited.has(method)) return;
+```
+
+**Optimize AST Parsing:**
+- [ ] Parse files only once, cache results
+- [ ] Skip node_modules and test files
+- [ ] Use ts-morph's built-in filters
+
+### 3. Code Simplification
+
+**Single Responsibility:**
+- [ ] `endpoint-detector.js` - Only finds affected endpoints
+- [ ] `method-call-graph.js` - Only builds call graphs
+- [ ] `ast-parser.js` - Only parses AST and extracts symbols
+
+**Remove Complex Logic:**
+- [ ] Remove async command/queue detection (move to separate detector if needed)
+- [ ] Focus on synchronous flow: Service → Controller → Endpoint
+- [ ] Remove SNS/SQS specific logic (too specific)
+
+**Simplified Algorithm:**
+```javascript
+// core/detectors/endpoint-detector.js
+export function findAffectedEndpoints(changedMethods, callGraph) {
+  const endpoints = [];
+  
+  for (const method of changedMethods) {
+    const found = traverseToEndpoint(method, callGraph);
+    endpoints.push(...found);
+  }
+  
+  return endpoints;
+}
+
+function traverseToEndpoint(method, callGraph, visited = new Set(), depth = 0) {
+  if (depth > 10 || visited.has(method)) return [];
+  visited.add(method);
+  
+  // Check if endpoint
+  if (isHttpEndpoint(method)) {
+    return [extractEndpointInfo(method)];
+  }
+  
+  // Traverse callers
+  const endpoints = [];
+  const callers = callGraph.getCallers(method);
+  
+  for (const caller of callers) {
+    const found = traverseToEndpoint(caller, callGraph, visited, depth + 1);
+    endpoints.push(...found);
+  }
+  
+  return endpoints;
+}
+```
+
+### 4. Logging with Verbose Mode
+
+**Add Verbose Flag:**
+```javascript
+// Pass verbose option from CLI
+const verbose = process.env.VERBOSE === 'true' || options.verbose;
+```
+
+**Logging Levels:**
+
+**Normal Mode (default):**
+- [ ] Log only essential info: Start, Progress, Results
+- [ ] No internal details
+- [ ] Clean output for CI/CD
+
+```javascript
+console.log('🔍 Analyzing API impacts...');
+console.log('📡 Found 3 affected endpoints');
+```
+
+**Verbose Mode (`--verbose`):**
+- [ ] Log each step of traversal
+- [ ] Show which methods are visited
+- [ ] Display decorator information
+- [ ] Show performance metrics
+
+```javascript
+if (verbose) {
+  console.log(`[API Detector] Starting traversal from: ${method.name}`);
+  console.log(`[API Detector] Visiting caller: ${caller.name} (depth: ${depth})`);
+  console.log(`[API Detector] Found endpoint: ${httpMethod} ${path}`);
+  console.log(`[API Detector] Completed in ${duration}ms`);
+}
+```
+
+**Implementation Pattern:**
+```javascript
+// core/utils/logger.js
+export function createLogger(verbose = false) {
+  return {
+    info: (msg) => console.log(msg),
+    debug: (msg) => verbose && console.log(`[DEBUG] ${msg}`),
+    verbose: (component, msg) => verbose && console.log(`[${component}] ${msg}`)
+  };
+}
+
+// Usage in endpoint-detector.js
+import { createLogger } from '../utils/logger.js';
+
+export function findAffectedEndpoints(methods, callGraph, options = {}) {
+  const logger = createLogger(options.verbose);
+  
+  logger.info('🔍 Analyzing API impacts...');
+  logger.verbose('EndpointDetector', `Processing ${methods.length} changed methods`);
+  
+  for (const method of methods) {
+    logger.verbose('EndpointDetector', `Traversing from: ${method.name}`);
+    // ... detection logic
+  }
+  
+  logger.info(`📡 Found ${endpoints.length} affected endpoints`);
+  return endpoints;
+}
+```
+
+### 5. Documentation Updates
+
+**File Headers:**
+```javascript
+/**
+ * @file endpoint-detector.js
+ * @description Detects API endpoints affected by code changes via call graph traversal
+ * 
+ * Algorithm:
+ * 1. Start from changed method
+ * 2. Traverse upward through callers
+ * 3. Stop when HTTP decorator found
+ * 4. Extract endpoint info (method, path)
+ * 
+ * @example
+ * const endpoints = findAffectedEndpoints(changedMethods, callGraph);
+ * // Returns: [{ method: 'GET', path: '/users/:id', ... }]
+ */
+```
+
+**Function JSDoc:**
+```javascript
+/**
+ * Find API endpoints affected by changed methods
+ * @param {Array<string>} changedMethods - List of changed method names
+ * @param {CallGraph} callGraph - Method call graph with caller/callee relationships
+ * @param {Object} options - Options { verbose: boolean }
+ * @returns {Array<Endpoint>} List of affected endpoints
+ */
+export function findAffectedEndpoints(changedMethods, callGraph, options = {}) {
+  // Implementation
+}
+```
+
+## ✅ Acceptance Criteria
+
+- [ ] All code moved to `core/` folder structure
+- [ ] No references to old `modules/` folder
+- [ ] Unused functions removed (document what was removed)
+- [ ] Performance improved (measure before/after)
+- [ ] Verbose mode works with `--verbose` flag
+- [ ] Normal mode shows clean output
+- [ ] All functions have JSDoc comments
+- [ ] Code follows single responsibility principle
+- [ ] Tests pass (if any exist)
+
+## 📊 Performance Targets
+
+- [ ] Call graph traversal: < 100ms for 1000 methods
+- [ ] Endpoint detection: < 50ms per changed method
+- [ ] Memory usage: < 500MB for large codebases
+
+## 🧪 Testing
+
+**Manual Test:**
+```bash
+# Normal mode
+node cli.js --input=src --base=origin/main
+
+# Verbose mode
+node cli.js --input=src --base=origin/main --verbose
+```
+
+**Expected Output (Normal):**
+```
+🔍 Analyzing code changes...
+📊 Found 5 changed methods
+🔍 Analyzing API impacts...
+📡 Found 3 affected endpoints
+✅ Analysis complete
+```
+
+**Expected Output (Verbose):**
+```
+🔍 Analyzing code changes...
+[ChangeDetector] Parsing git diff: origin/main..HEAD
+[ChangeDetector] Found 2 modified files
+[ChangeDetector] Extracted 5 changed methods
+📊 Found 5 changed methods
+
+🔍 Analyzing API impacts...
+[EndpointDetector] Processing 5 changed methods
+[EndpointDetector] Traversing from: UserService.updateEmail
+[EndpointDetector] Visiting caller: UserController.updateProfile (depth: 1)
+[EndpointDetector] Found endpoint: PUT /users/:id
+[EndpointDetector] Completed in 45ms
+📡 Found 3 affected endpoints
+✅ Analysis complete
+```
+
+## 📚 References
+
+- API Impact Detection Spec: `.specify/specs/features/api-impact-detection.md`
+- Architecture Doc: `.specify/plans/architecture.md`
+- Code Rules: `.github/copilot-instructions.md`