@sun-asterisk/impact-analyzer 1.0.4 → 1.0.6

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

@@ -0,0 +1,247 @@
+# Feature Spec: Database Impact Detection
+
+## 1. Overview
+
+Identify database tables and models affected by code changes.  This helps developers understand data layer impacts and plan database-related testing or migrations.
+
+## 2. User Story
+
+> As a developer reviewing a pull request,
+> I want to see which database tables are affected by the code changes,
+> So that I can assess data integrity risks and plan database testing.
+
+## 3. Functional Requirements
+
+### FR-001: Detect Entity/Model Changes
+- **Description**:  Identify changes to ORM entity or model files
+- **Patterns to Support**:
+  - TypeORM:  `@Entity()` decorator
+  - Sequelize: `@Table()` decorator, `Model.init()`
+  - Mongoose: `mongoose.model()`, `new Schema()`
+  - Prisma:  Changes to `schema.prisma`
+- **Acceptance Criteria**:
+  - Detects new entity definitions
+  - Detects modified entity properties
+  - Detects deleted entities
+  - Detects relation changes
+
+### FR-002: Extract Table Names
+- **Description**:  Determine database table name from entity definition
+- **Sources**:
+  - Explicit table name in decorator:  `@Entity('users')`
+  - Decorator options: `@Entity({ name: 'users' })`
+  - Class name conversion (PascalCase → snake_case)
+  - Sequelize tableName option
+  - Mongoose collection name
+- **Acceptance Criteria**:
+  - Correctly extracts explicit table names
+  - Correctly converts class names when not specified
+  - Handles custom naming strategies
+
+### FR-003: Detect Repository/DAO Changes
+- **Description**: Find changes to data access layer code
+- **Patterns to Support**:
+  - TypeORM Repository pattern
+  - Custom repository classes
+  - Query builder usage
+  - Raw SQL queries
+- **Acceptance Criteria**:
+  - Identifies affected entity from repository
+  - Detects query method changes
+  - Identifies CRUD operations
+
+### FR-004: Classify Impact Type
+- **Description**:  Categorize the type of database impact
+- **Categories**:
+  - `schema`: Column/property changes, new entities
+  - `query`: Repository method changes
+  - `relation`: Foreign key/relation changes
+  - `migration`: Migration file changes
+- **Acceptance Criteria**:
+  - Correctly classifies schema changes
+  - Correctly classifies query-only changes
+  - Correctly classifies relation changes
+
+### FR-005: Identify CRUD Operations
+- **Description**: Determine which database operations are affected
+- **Operations**:  SELECT, INSERT, UPDATE, DELETE
+- **Detection Methods**:
+  - Method name analysis (find*, create*, update*, delete*)
+  - Query builder analysis
+  - Decorator analysis (@Query, etc.)
+- **Acceptance Criteria**:
+  - Correctly identifies read operations
+  - Correctly identifies write operations
+  - Handles mixed operations
+
+### FR-006: Generate Database Report
+- **Description**:  Compile database impacts into structured report
+- **Output**: `DatabaseImpact[]` array
+- **Acceptance Criteria**:
+  - Includes table name and model name
+  - Includes impact classification
+  - Includes affected operations
+  - Deduplicates by table/impact type
+
+## 4. Non-Functional Requirements
+
+### NFR-001: Performance
+- Analysis should add <5 seconds to total analysis time
+
+### NFR-002: Accuracy
+- Should detect >95% of schema changes
+- Should detect >85% of query changes
+
+## 5. Output Schema
+
+```javascript
+/**
+ * @typedef {Object} DatabaseImpact
+ * @property {string} tableName - Database table name (snake_case)
+ * @property {string} modelName - Entity/Model class name
+ * @property {string} modelPath - File path to model definition
+ * @property {'schema'|'query'|'relation'|'migration'} impactType
+ * @property {('SELECT'|'INSERT'|'UPDATE'|'DELETE')[]} operations
+ * @property {FileChange} changeSource
+ * @property {'low'|'medium'|'high'|'critical'} severity
+ */
+```
+
+## 6. Severity Classification
+
+| Severity | Criteria |
+|----------|----------|
+| Critical | Schema changes (columns, constraints) |
+| High | Relation changes, DELETE operations |
+| Medium | INSERT, UPDATE operations |
+| Low | SELECT-only query changes |
+
+## 7. ORM Detection Patterns
+
+### TypeORM
+```javascript
+// Entity detection
+@Entity('users')
+@Entity({ name: 'users' })
+class User { }
+
+// Column detection
+@Column()
+@PrimaryColumn()
+@PrimaryGeneratedColumn()
+
+// Relation detection
+@OneToMany()
+@ManyToOne()
+@OneToOne()
+@ManyToMany()
+
+// Repository detection
+class UserRepository extends Repository<User> { }
+@EntityRepository(User)
+```
+
+### Sequelize
+```javascript
+// Model detection
+@Table({ tableName: 'users' })
+class User extends Model { }
+
+User.init({ }, { tableName: 'users' })
+
+// Column detection
+@Column
+@PrimaryKey
+@AutoIncrement
+
+// Relation detection
+@HasMany()
+@BelongsTo()
+@BelongsToMany()
+```
+
+### Mongoose
+```javascript
+// Schema detection
+const userSchema = new Schema({ })
+mongoose.model('User', userSchema)
+
+// Collection override
+mongoose.model('User', userSchema, 'custom_users')
+```
+
+### Prisma
+```prisma
+// Model detection in schema. prisma
+model User {
+  id    Int     @id @default(autoincrement())
+  email String  @unique
+  posts Post[]
+}
+```
+
+## 8. Test Scenarios
+
+### Scenario 1: Entity Column Change
+- **Given**: A property in an entity class is modified
+- **When**: Analysis runs
+- **Then**: Impact type is "schema" with high severity
+
+### Scenario 2: New Relation Added
+- **Given**:  A new relation decorator is added
+- **When**: Analysis runs
+- **Then**: Impact type is "relation"
+
+### Scenario 3: Repository Query Change
+- **Given**: A repository method is modified
+- **When**: Analysis runs
+- **Then**: Impact type is "query" with affected operations
+
+### Scenario 4: Prisma Schema Change
+- **Given**: schema.prisma is modified
+- **When**:  Analysis runs
+- **Then**:  Affected models are detected
+
+## 9. Edge Cases
+
+| Case | Expected Behavior |
+|------|-------------------|
+| No ORM detected | Return empty array |
+| Dynamic table names | Log warning, use class name |
+| Abstract entities | Skip, not mapped to table |
+| Embedded entities | Include in parent entity impact |
+| View entities | Mark as "view" in output |
+
+## 10. Example
+
+### Input
+```javascript
+// Changed file: src/entities/user.entity. js
+// Modified lines: 8-10
+
+@Entity('users')
+class User {
+  @Column()
+  email;  // Line 8 - CHANGED
+
+  @Column({ nullable: true })  // Line 9 - ADDED
+  phone;  // Line 10 - ADDED
+}
+```
+
+### Expected Output
+```javascript
+{
+  database: [
+    {
+      tableName: "users",
+      modelName: "User",
+      modelPath: "src/entities/user.entity.js",
+      impactType: "schema",
+      operations: ["SELECT", "INSERT", "UPDATE"],
+      changeSource:  { path: "src/entities/user. entity.js", ...  },
+      severity:  "critical"
+    }
+  ]
+}
+```

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`