@sun-asterisk/impact-analyzer 1.0.4 → 1.0.5

package/.specify/plans/architecture.md

@@ -0,0 +1,186 @@
+# Impact Analyzer - Architecture
+
+## What This Tool Does
+
+Analyzes code changes in TypeScript/JavaScript projects to identify impacts on APIs, databases, and logic dependencies. Generates severity-based reports (LOW/MEDIUM/HIGH/CRITICAL).
+
+## System Architecture
+
+High-level flow through 4 stages:
+
+**Stage 1: Change Detection** (`change-detector.js`)
+- Parse git diff to find changed files
+- Extract modified symbols using AST parser
+- Output: List of changed methods/functions/classes
+
+**Stage 2: Call Graph Building** (`method-call-graph.js`, `dependency-graph.js`)
+- Parse all source files with ts-morph
+- Build method-to-caller relationships
+- Build method-to-callee relationships
+- Map HTTP decorators to methods
+- Output: Complete call graph
+
+**Stage 3: Impact Detection** (`detectors/`)
+- Endpoint Detector: Traverse call graph upward to find affected API endpoints
+- Database Detector: Detect DB operations and extract table/field information
+- Output: Affected endpoints + DB impacts
+
+**Stage 4: Report Generation** (`report-generator.js`)
+- Calculate impact score based on endpoints, DB ops, and callers
+- Apply severity multipliers
+- Generate console/markdown/JSON reports
+- Output: Final impact report with severity level
+
+## File Structure
+
+```
+core/
+├── change-detector.js           # Git diff + AST extraction
+├── impact-analyzer.js           # Main orchestrator
+├── report-generator.js          # Score calculation + output
+├── detectors/
+│   ├── endpoint-detector.js     # API impact via call graph traversal
+│   └── database-detector.js     # DB impact via pattern detection
+└── utils/
+    ├── ast-parser.js            # Parse TS/JS with ts-morph
+    ├── method-call-graph.js     # Build method-level call graphs
+    ├── dependency-graph.js      # Track file/module dependencies
+    ├── file-utils.js            # File system operations
+    └── git-utils.js             # Git operations (diff, show)
+```
+
+## Key Algorithms
+
+### 1. Call Graph Traversal (Endpoint Detection)
+
+```javascript
+// Find endpoints affected by changed method
+function findAffectedEndpoints(changedMethod, callGraph) {
+  const visited = new Set();
+  const endpoints = [];
+  
+  // Traverse upward through callers
+  function traverseUp(method) {
+    if (visited.has(method)) return;
+    visited.add(method);
+    
+    const callers = callGraph.getCallers(method);
+    for (const caller of callers) {
+      // Check if this caller is an endpoint
+      if (hasHttpDecorator(caller)) {
+        endpoints.push(extractEndpointInfo(caller));
+      } else {
+        // Continue traversing up
+        traverseUp(caller);
+      }
+    }
+  }
+  
+  traverseUp(changedMethod);
+  return endpoints;
+}
+```
+
+### 2. Database Impact Detection
+
+```javascript
+// Detect DB operations in repository methods
+function detectDatabaseImpact(changedFile, ast) {
+  const impacts = [];
+  
+  // Find repository layer methods
+  const repoMethods = findRepositoryMethods(ast);
+  
+  for (const method of repoMethods) {
+    // Look for ORM calls: find, save, update, delete
+    const dbCalls = findDatabaseCalls(method);
+    
+    for (const call of dbCalls) {
+      impacts.push({
+        table: extractTableName(call),
+        fields: extractFields(call),
+        operation: getOperationType(call), // READ/WRITE
+        orm: detectORM(call) // TypeORM/Prisma/etc
+      });
+    }
+  }
+  
+  return impacts;
+}
+```
+
+### 3. Impact Score Calculation
+
+```javascript
+function calculateImpactScore(impacts) {
+  let score = 0;
+  
+  // Base scoring
+  score += impacts.endpoints.length * 10;
+  score += impacts.dbTables.length * 5;
+  score += impacts.directCallers.length * 3;
+  score += impacts.indirectCallers.length * 1;
+  
+  // Apply multipliers
+  if (impacts.hasHighRiskLogic) {
+    score *= 1.5;
+  }
+  if (impacts.hasDatabaseMigration) {
+    score += 20;
+  }
+  
+  // Determine severity
+  const severity = 
+    score < 21 ? 'LOW' :
+    score < 51 ? 'MEDIUM' :
+    score < 101 ? 'HIGH' : 'CRITICAL';
+  
+  return { score, severity };
+}
+```
+
+## Framework Support
+
+### Supported Patterns
+
+**Backend Frameworks:**
+- NestJS: `@Controller`, `@Get`, `@Post`, `@Put`, `@Delete`
+- Express: `router.get()`, `router.post()`, etc.
+- Fastify: `fastify.get()`, `fastify.post()`, etc.
+
+**ORM Frameworks:**
+- TypeORM: `@Entity`, `@Table`, `find()`, `save()`, `update()`
+- Prisma: `prisma.model.findMany()`, `prisma.model.create()`
+- Sequelize: `Model.findAll()`, `Model.create()`
+
+**Detection Strategy:**
+1. Parse decorators (`@Controller`, `@Entity`)
+2. Match method call patterns (`find`, `save`)
+3. Extract metadata (route paths, table names)
+
+## Design Principles
+
+**1. Single Responsibility**
+- Each module has one clear purpose
+- Detectors are independent and composable
+
+**2. Layer-Aware Analysis**
+```
+Database Layer (Repository)
+         ↓
+Business Layer (Service)
+         ↓
+Presentation Layer (Controller)
+         ↓
+API Endpoints
+```
+
+**3. Optimized Parsing**
+- Only parse source files (skip node_modules)
+- Build call graph once, reuse for all detectors
+- Stream processing for large codebases
+
+**4. Extensible Detection**
+- Add new detectors without modifying core
+- Framework patterns defined in config
+- Custom rules per project

package/.specify/specs/features/api-impact-detection.md

@@ -0,0 +1,317 @@
+# Feature Spec: API Impact Detection
+
+## What It Does
+
+Finds API endpoints affected by code changes using call graph traversal.
+
+## How It Works
+
+**Input:** Changed methods from git diff  
+**Output:** List of affected API endpoints with HTTP method and path
+
+### Algorithm
+
+```javascript
+function findAffectedEndpoints(changedMethod, callGraph) {
+  // 1. Start from changed method
+  // 2. Traverse upward through callers
+  // 3. Stop when reaching method with HTTP decorator
+  // 4. Extract endpoint info (method, path)
+  
+  const endpoints = [];
+  const visited = new Set();
+  
+  function traverse(method) {
+    if (visited.has(method)) return;
+    visited.add(method);
+    
+    // Check if this is an endpoint
+    if (hasHttpDecorator(method)) {
+      endpoints.push({
+        httpMethod: extractHttpMethod(method),
+        path: extractPath(method),
+        controller: method.name
+      });
+      return;
+    }
+    
+    // Continue traversing up
+    const callers = callGraph.getCallers(method);
+    callers.forEach(traverse);
+  }
+  
+  traverse(changedMethod);
+  return endpoints;
+}
+```
+
+### Flow Example
+
+**Synchronous (Direct Call):**
+```
+Changed: UserService.updateEmail()
+         ↓
+Caller:  UserController.updateProfile()
+         ↓
+Check:   Has @Put(':id') decorator
+         ↓
+Output:  PUT /users/:id
+```
+
+**Asynchronous (Command/Queue):**
+```
+Changed: OrderService.processOrder()
+         ↓
+Caller:  ProcessOrderHandler.handle()
+         ↓
+Check:   Has @Process('processOrder') decorator
+         ↓
+Search:  Find where 'processOrder' command is published
+         ↓
+Found:   OrderController.create() with queue.add('processOrder')
+         ↓
+Check:   Has @Post('orders') decorator
+         ↓
+Output:  POST /orders (via command: processOrder)
+```
+
+## Supported Frameworks
+
+### NestJS (Primary)
+
+**HTTP Decorators:**
+- `@Controller('path')` - Base path
+- `@Get('subpath')` - GET method
+- `@Post('subpath')` - POST method
+- `@Put('subpath')` - PUT method
+- `@Delete('subpath')` - DELETE method
+- `@Patch('subpath')` - PATCH method
+
+**Queue/Command Decorators:**
+- `@Process('commandName')` - Queue processor
+- `@OnQueueCompleted()` - Queue event handler
+
+```javascript
+// Detection logic for HTTP endpoints
+function hasHttpDecorator(method) {
+  const decorators = ['Get', 'Post', 'Put', 'Delete', 'Patch'];
+  return method.decorators.some(d => decorators.includes(d.name));
+}
+
+// Detection logic for queue handlers
+function isQueueHandler(method) {
+  return method.decorators.some(d => d.name === 'Process');
+}
+
+function extractCommandName(method) {
+  const processDecorator = method.decorators.find(d => d.name === 'Process');
+  return processDecorator?.arguments[0]; // Returns 'processOrder'
+}
+
+function extractEndpointInfo(method) {
+  const httpDecorator = method.decorators.find(d => 
+    ['Get', 'Post', 'Put', 'Delete', 'Patch'].includes(d.name)
+  );
+  
+  const controllerDecorator = method.class.decorators.find(d => 
+    d.name === 'Controller'
+  );
+  
+  return {
+    method: httpDecorator.name.toUpperCase(),
+    path: joinPath(
+      controllerDecorator.arguments[0],
+      httpDecorator.arguments[0]
+    )
+  };
+}
+```
+
+### Express
+
+Detect route definitions:
+- `router.get(path, handler)`
+- `router.post(path, handler)`
+- `app.get(path, handler)`
+
+```javascript
+// Detection logic
+function isExpressRoute(callExpression) {
+  const methods = ['get', 'post', 'put', 'delete', 'patch'];
+  return callExpression.expression.object.name === 'router' &&
+         methods.includes(callExpression.expression.property.name);
+}
+```
+
+## Async Patterns (Command/Queue)
+
+### Queue Publishers
+
+Detect queue/command publishing patterns:
+- BullMQ: `queue.add('commandName', data)`
+- NestJS Queue: `await this.queue.add('commandName', data)`
+- AWS SQS: `await sqs.send({ command: 'commandName' })`
+- AWS SNS: `await sns.send({ message: { command: 'commandName' } })`
+- Command Bus: `await commandBus.execute('commandName', data)`
+
+### Detection Algorithm for Async Flow
+
+```javascript
+function findAsyncEndpoints(changedMethod, callGraph) {
+  const endpoints = [];
+  
+  // 1. Traverse up to find queue handler
+  const handler = findQueueHandler(changedMethod, callGraph);
+  if (!handler) return endpoints;
+  
+  // 2. Extract command name from handler decorator
+  const commandName = extractCommandName(handler);
+  if (!commandName) return endpoints;
+  
+  // 3. Search for publishers of this command
+  const publishers = findCommandPublishers(commandName);
+  
+  // 4. For each publisher, find the endpoint
+  for (const publisher of publishers) {
+    const endpoint = findEndpointForMethod(publisher, callGraph);
+    if (endpoint) {
+      endpoints.push({
+        ...endpoint,
+        flow: 'async',
+        command: commandName,
+        handler: handler.name
+      });
+    }
+  }
+  
+  return endpoints;
+}
+
+function findQueueHandler(method, callGraph) {
+  const callers = callGraph.getCallers(method);
+  for (const caller of callers) {
+    if (isQueueHandler(caller)) {
+      return caller;
+    }
+  }
+  return null;
+}
+
+function findCommandPublishers(commandName) {
+  // Search all files for queue.add('commandName')
+  const publishers = [];
+  const pattern = new RegExp(`\\.add\\(['"\`]${commandName}['"\`]`);
+  
+  // Use AST to find call expressions matching pattern
+  // Returns array of methods that publish this command
+  
+  return publishers;
+}
+```
+
+### Example: Async Flow
+
+```typescript
+// Controller publishes command
+@Controller('orders')
+class OrderController {
+  @Post()
+  async create(@Body() dto: CreateOrderDto) {
+    const command = 'processOrder';
+    await this.sns.publishMessage({
+      message: { command: command, payload: dto }
+    });
+
+    return { success: true };
+  }
+}
+
+// Case 1. Handler processes command
+@Processor('orderQueue')
+class OrderProcessor {
+  @Process('processOrder')
+  async handle(job: Job) {
+    await this.orderService.processOrder(job.data); // Changed method
+  }
+}
+
+// Case 2. Handler command by nest
+@command({name: 'processOrder'})
+export class OrderCommand extends CommonComand {
+  async run() {
+    await this.orderService.processOrder(job.data); // Changed method
+  }
+
+// Service method (changed)
+class OrderService {
+  async processOrder(data) {
+    // Implementation changed here
+  }
+}
+
+// Detection result:
+// POST /orders (via command: processOrder)
+```
+
+## Output Structure
+
+**Synchronous Endpoint:**
+```javascript
+{
+  type: 'endpoint',
+  flow: 'sync',
+  method: 'PUT',           // HTTP method
+  path: '/users/:id',      // Route path
+  controller: 'UserController.updateProfile',
+  changedMethod: 'UserService.updateEmail',
+  file: 'src/services/user.service.js'
+}
+```
+
+**Asynchronous Endpoint:**
+```javascript
+{
+  type: 'endpoint',
+  flow: 'async',
+  method: 'POST',
+  path: '/orders',
+  controller: 'OrderController.create',
+  command: 'processOrder',        // Command name
+  handler: 'OrderProcessor.handle', // Handler method
+  changedMethod: 'OrderService.processOrder',
+  file: 'src/services/order.service.js'
+}
+```
+
+## Implementation Notes
+
+**Call Graph Building:**
+- Use `ts-morph` to parse TypeScript/JavaScript files
+- Build reverse map: method → callers
+- Store decorator information on methods
+- Store command names from queue operations
+
+**Traversal Strategy:**
+- BFS (breadth-first search) to find closest endpoints first
+- Stop at HTTP decorators (sync) or queue handlers (async)
+- Track visited nodes to avoid cycles
+- Max depth: 10 levels
+
+**Async Detection Strategy:**
+1. Traverse up from changed method to find queue handler
+2. Extract command name from `@Process('commandName')`
+3. Search codebase for `queue.add('commandName')` patterns
+4. Find endpoint that publishes the command
+5. Combine handler info with endpoint info
+
+**Path Construction:**
+- Combine `@Controller` path with HTTP decorator path
+- Handle dynamic segments (`:id`, `:slug`)
+- Normalize paths (remove trailing slashes)
+
+**Edge Cases:**
+- Skip if circular dependency detected
+- Skip if max depth reached
+- Report multiple endpoints if method has multiple callers
+- For async: Skip if command name is dynamic/variable
+- For async: Mark as external if command publisher not found