@sun-asterisk/impact-analyzer 1.0.4 → 1.0.6

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

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

@@ -0,0 +1,263 @@
+# Feature Spec:  Component Impact Detection
+
+## 1. Overview
+
+Identify UI components affected by code changes.  This feature traces component dependencies to find parent components that may be impacted by changes to child components.
+
+## 2. User Story
+
+> As a developer reviewing a pull request,
+> I want to see which UI components are affected by the code changes,
+> So that I can plan visual testing and assess user-facing impact.
+
+## 3. Functional Requirements
+
+### FR-001: Detect Component Definitions
+- **Description**:  Identify React/Vue/Angular component definitions
+- **Patterns to Support**:
+  - React functional components
+  - React class components
+  - React. FC type annotation
+  - Vue Single File Components (SFC)
+  - Vue Composition API (script setup)
+  - Angular @Component decorator
+- **Acceptance Criteria**:
+  - Detects function components (named and arrow)
+  - Detects class components extending React.Component
+  - Detects Vue SFC script blocks
+  - Detects Angular component classes
+
+### FR-002: Build Component Dependency Tree
+- **Description**:  Map component import/usage relationships
+- **Input**: Changed component names
+- **Output**:  Tree of parent components
+- **Acceptance Criteria**:
+  - Traces JSX/TSX component usage
+  - Resolves import statements
+  - Handles re-exports
+  - Handles dynamic imports
+
+### FR-003: Detect Props/Interface Changes
+- **Description**: Identify changes to component props
+- **Patterns to Support**:
+  - TypeScript interface:  `interface Props { }`
+  - TypeScript type: `type Props = { }`
+  - PropTypes definition
+  - Vue defineProps
+  - Angular @Input() decorator
+- **Acceptance Criteria**:
+  - Detects added props
+  - Detects removed props
+  - Detects prop type changes
+  - Flags breaking prop changes
+
+### FR-004: Find Parent Components
+- **Description**: Locate all components that use the changed component
+- **Input**: Changed component name and file
+- **Output**: List of parent components with usage count
+- **Acceptance Criteria**:
+  - Searches all component files in project
+  - Finds JSX usage:  `<ComponentName />`
+  - Handles aliased imports
+  - Counts usage instances
+
+### FR-005: Classify Component Type
+- **Description**:  Categorize the component framework and style
+- **Types**:
+  - `react-functional`: React function components
+  - `react-class`: React class components
+  - `vue-sfc`: Vue Single File Components
+  - `vue-composition`: Vue Composition API
+  - `angular`: Angular components
+- **Acceptance Criteria**:
+  - Correctly identifies React components
+  - Correctly identifies Vue components
+  - Correctly identifies Angular components
+
+### FR-006: Generate Component Report
+- **Description**: Compile component impacts into structured report
+- **Output**:  `ComponentImpact[]` array
+- **Acceptance Criteria**:
+  - Includes component name and type
+  - Includes parent component list
+  - Indicates props changes
+  - Includes severity based on usage
+
+## 4. Non-Functional Requirements
+
+### NFR-001: Performance
+- Analysis should add <10 seconds to total analysis time
+- Should handle projects with 500+ components
+
+### NFR-002: Accuracy
+- Should detect >90% of component changes
+- Should find >85% of parent component relationships
+
+## 5. Output Schema
+
+```javascript
+/**
+ * @typedef {Object} ComponentImpact
+ * @property {string} componentName - Component name
+ * @property {string} filePath - Path to component file
+ * @property {'react-functional'|'react-class'|'vue-sfc'|'vue-composition'|'angular'} componentType
+ * @property {ParentComponent[]} parentComponents
+ * @property {boolean} propsChanged - Whether props interface was modified
+ * @property {FileChange} changeSource
+ * @property {'low'|'medium'|'high'|'critical'} severity
+ */
+
+/**
+ * @typedef {Object} ParentComponent
+ * @property {string} name - Parent component name
+ * @property {string} filePath - Path to parent component
+ * @property {number} usageCount - How many times child is used
+ */
+```
+
+## 6. Severity Classification
+
+| Severity | Criteria |
+|----------|----------|
+| Critical | Props changed + >10 parent components |
+| High | Props changed OR >10 parent components |
+| Medium | 3-10 parent components |
+| Low | <3 parent components |
+
+## 7. Component Detection Patterns
+
+### React Functional Components
+```javascript
+// Named function
+function Button({ label }) {
+  return <button>{label}</button>;
+}
+
+// Arrow function
+const Button = ({ label }) => <button>{label}</button>;
+
+// React. FC type
+const Button:  React.FC<ButtonProps> = ({ label }) => { };
+
+// forwardRef
+const Button = forwardRef((props, ref) => { });
+
+// memo
+const Button = memo(({ label }) => { });
+```
+
+### React Class Components
+```javascript
+class Button extends React.Component { }
+class Button extends Component { }
+class Button extends React.PureComponent { }
+```
+
+### Vue Components
+```vue
+<!-- Options API -->
+<script>
+export default {
+  name: 'Button',
+  props: { label: String }
+}
+</script>
+
+<!-- Composition API -->
+<script setup>
+defineProps({ label: String })
+</script>
+```
+
+### Angular Components
+```typescript
+@Component({
+  selector: 'app-button',
+  template: '<button>{{label}}</button>'
+})
+export class ButtonComponent {
+  @Input() label: string;
+}
+```
+
+## 8. Test Scenarios
+
+### Scenario 1: Direct Component Change
+- **Given**:  A component's JSX is modified
+- **When**: Analysis runs
+- **Then**:  Component is detected with its parent components
+
+### Scenario 2: Props Interface Change
+- **Given**: A component's Props interface is modified
+- **When**: Analysis runs
+- **Then**:  `propsChanged` is true and severity is elevated
+
+### Scenario 3: Shared Component Change
+- **Given**:  A shared component (used by 15+ parents) is modified
+- **When**: Analysis runs
+- **Then**:  All parent components are listed, severity is high
+
+### Scenario 4: Isolated Component Change
+- **Given**: A component with no parents is modified
+- **When**: Analysis runs
+- **Then**: Component is detected with empty parent list
+
+### Scenario 5: Style-Only Change
+- **Given**: Only CSS/styles in a component file change
+- **When**:  Analysis runs
+- **Then**: Component is detected with low severity
+
+## 9. Edge Cases
+
+| Case | Expected Behavior |
+|------|-------------------|
+| Higher-order components | Detect both wrapper and wrapped |
+| Render props | Detect component, not render function |
+| Context providers | Detect as component |
+| CSS-only files | Skip, not a component |
+| Test files | Skip (excluded by pattern) |
+| Storybook files | Skip (excluded by pattern) |
+
+## 10. Example
+
+### Input
+```javascript
+// Changed file: src/components/Button/Button.jsx
+// Modified lines: 5-8
+
+/**
+ * @typedef {Object} ButtonProps
+ * @property {string} label
+ * @property {string} variant  // Line 5 - ADDED
+ * @property {() => void} onClick
+ */
+
+function Button({ label, variant, onClick }) {  // Line 8 - CHANGED
+  return (
+    <button className={variant} onClick={onClick}>
+      {label}
+    </button>
+  );
+}
+```
+
+### Expected Output
+```javascript
+{
+  component: [
+    {
+      componentName: "Button",
+      filePath:  "src/components/Button/Button.jsx",
+      componentType: "react-functional",
+      parentComponents: [
+        { name: "Header", filePath: "src/components/Header. jsx", usageCount: 2 },
+        { name: "Modal", filePath: "src/components/Modal.jsx", usageCount: 1 },
+        { name: "Form", filePath: "src/components/Form.jsx", usageCount: 3 }
+      ],
+      propsChanged: true,
+      changeSource: { path:  "src/components/Button/Button.jsx", ... },
+      severity: "medium"
+    }
+  ]
+}
+```