@sun-asterisk/impact-analyzer 1.0.4 → 1.0.5

package/.github/copilot-instructions.md

@@ -0,0 +1,116 @@
+# Impact Analyzer - AI Code Generation Guide
+
+## 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).
+
+## Architecture
+
+```
+core/
+├── change-detector.js           # Git diff parsing + AST symbol extraction
+├── impact-analyzer.js           # Main orchestrator
+├── report-generator.js          # Console/markdown/JSON output
+├── detectors/
+│   ├── endpoint-detector.js     # Find affected API endpoints
+│   └── database-detector.js     # Detect DB table/field changes
+└── utils/
+    ├── ast-parser.js            # Parse TS/JS with ts-morph
+    ├── method-call-graph.js     # Build caller/callee maps
+    ├── dependency-graph.js      # Track dependencies
+    ├── file-utils.js            # File operations
+    └── git-utils.js             # Git operations
+```
+
+## Core Logic Flow
+
+1. **Detect Changes** → Parse git diff, extract changed symbols
+2. **Build Call Graph** → Map methods to callers/callees
+3. **Find Impacts** → Traverse graph upward to find affected endpoints and DB ops
+4. **Calculate Score** → Score = (Endpoints×10) + (DB×5) + (Callers×3) + (Indirect×1)
+5. **Generate Report** → Output with severity level
+
+## Code Rules for AI Generation
+
+### Essential Patterns
+
+**Import/Export**
+```javascript
+import { Project } from 'ts-morph';
+export function analyzeImpact(files) { }
+```
+
+**Async Operations**
+```javascript
+async function detectChanges() {
+  const files = await getChangedFiles();
+  return await Promise.all(files.map(analyzeFile));
+}
+```
+
+**Error Handling**
+```javascript
+try {
+  await operation();
+} catch (error) {
+  console.error('Context:', { file, method }, error);
+}
+```
+
+**Call Graph Traversal**
+```javascript
+function findAffectedEndpoints(method, callGraph) {
+  const callers = traverseUpward(method, callGraph);
+  return callers.filter(hasHttpDecorator);
+}
+```
+
+### Code Quality Rules
+
+- **Rule C005** - One function does one thing
+- **Rule C006** - Function names use verb-noun (e.g., `detectEndpoints`, `buildCallGraph`)
+- **Rule C007** - No comments that restate code
+- **Rule C015** - Use domain language (e.g., `endpoint`, `impact`, `severity`)
+- **Rule C031** - Separate validation logic
+- **Rule C033** - Separate data access from business logic
+
+### Naming Conventions
+
+- Functions: `camelCase` (e.g., `analyzeImpact`)
+- Classes: `PascalCase` (e.g., `ImpactAnalyzer`)
+- Constants: `UPPER_SNAKE_CASE` (e.g., `SEVERITY_LEVELS`)
+- Files: `kebab-case.js` (e.g., `call-graph.js`)
+
+### Required Patterns
+
+**Always use:**
+- ES Modules (`import/export`)
+- `async/await` (never callbacks)
+- `ts-morph` for AST parsing
+- Descriptive variable names from domain
+
+**Never do:**
+- Use `new` in business logic (use dependency injection)
+- Log errors without context
+- Mix validation with business logic
+- Return raw strings from API handlers
+
+## CLI Usage
+
+```bash
+# Basic
+npx @sun-asterisk/impact-analyzer --input=src --base=origin/main
+
+# With reports
+npx @sun-asterisk/impact-analyzer --input=src --base=origin/main --output=report.md --json=report.json
+```
+
+## Severity Calculation
+
+```javascript
+score = (endpoints × 10) + (dbTables × 5) + (directCallers × 3) + (indirectCallers × 1)
+if (highRiskLogic) score *= 1.5
+if (dbMigration) score += 20
+
+severity = score < 21 ? 'LOW' : score < 51 ? 'MEDIUM' : score < 101 ? 'HIGH' : 'CRITICAL'
+```

package/.github/prompts/README.md

@@ -0,0 +1,91 @@
+# Prompts for GitHub Copilot CLI
+
+## Do You Need Prompts?
+
+**Short Answer: NO** - For most tasks, you can directly reference the task file:
+
+```bash
+# Direct approach (RECOMMENDED)
+@task-001-refactor-api-detector.md read this task and implement it
+```
+
+**Why Direct Reference Works:**
+- Task files are already structured for AI (clear goals, code examples, acceptance criteria)
+- GitHub Copilot CLI can read and understand markdown task files directly
+- Less overhead, fewer files to maintain
+- Task files contain all necessary context
+
+## When to Use Prompts?
+
+Use prompts ONLY when you need to:
+
+1. **Reuse across multiple tasks** - Common patterns used in many places
+2. **Add constraints not in task** - Team-specific rules, environment limitations
+3. **Provide context not in codebase** - External dependencies, business rules
+4. **Break down complex tasks** - Multi-step workflows that need orchestration
+
+## Current Prompts
+
+### task-001-refactor.prompt.md
+
+**Purpose:** Provides step-by-step implementation guide for Task 001 refactoring
+
+**Why it exists:**
+- Breaks down large refactor into smaller, sequential steps
+- Adds verification steps after each phase
+- Includes rollback instructions for safety
+- Provides consistent implementation pattern for future refactors
+
+**When to use:**
+```bash
+# Step-by-step guided refactor
+@task-001-refactor.prompt.md implement this refactor step by step
+```
+
+**When NOT to use:**
+```bash
+# Simple, direct implementation
+@task-001-refactor-api-detector.md implement this task
+```
+
+## Prompt Guidelines
+
+If you create a new prompt, follow these rules:
+
+**Keep it simple:**
+- One prompt = One specific purpose
+- Max 100 lines
+- Clear structure with sections
+
+**Make it actionable:**
+- Use concrete code examples
+- Provide expected outcomes
+- Include verification commands
+
+**Avoid duplication:**
+- Don't repeat what's in task files
+- Don't repeat what's in copilot-instructions.md
+- Reference existing docs instead
+
+## Prompt Template
+
+```markdown
+# Prompt: [Name]
+
+## Purpose
+[Why this prompt exists]
+
+## Context
+[What AI needs to know]
+
+## Implementation Steps
+1. [Step 1]
+2. [Step 2]
+...
+
+## Verification
+[How to verify it worked]
+
+## References
+- [Link to related docs]
+```

package/.github/prompts/task-001-refactor.prompt.md

@@ -0,0 +1,241 @@
+# Prompt: Task 001 Refactor Implementation
+
+## Purpose
+
+Step-by-step implementation guide for refactoring API detector from modules/ to core/ with performance optimization.
+
+## Why This Prompt Exists
+
+While the task file contains all requirements, this prompt:
+1. **Breaks down into safe phases** - Prevents breaking changes
+2. **Adds verification steps** - Ensures each phase works before moving on
+3. **Provides rollback strategy** - Safety net if something goes wrong
+4. **Sequential execution** - Avoids doing everything at once
+
+## Phase 1: Audit Current Structure
+
+**Goal:** Understand what exists before changing it
+
+```bash
+# Find all files in modules/ or related to API detection
+find . -name "*api*" -o -name "*endpoint*" -o -name "*detector*" | grep -v node_modules
+
+# Check imports
+grep -r "from.*modules" --include="*.js" | head -20
+```
+
+**Document:**
+- Which files exist?
+- Which files import from modules/?
+- Are there tests?
+
+## Phase 2: Create New Structure (No Breaking Changes)
+
+**Goal:** Create new files in core/ without touching old code
+
+```javascript
+// Step 1: Create 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}`)
+  };
+}
+
+// Step 2: Create core/detectors/endpoint-detector.js
+// Copy existing logic, add logger, optimize
+import { createLogger } from '../utils/logger.js';
+
+export function findAffectedEndpoints(changedMethods, callGraph, options = {}) {
+  const logger = createLogger(options.verbose);
+  const endpoints = [];
+  
+  logger.info('🔍 Analyzing API impacts...');
+  logger.verbose('EndpointDetector', `Processing ${changedMethods.length} methods`);
+  
+  for (const method of changedMethods) {
+    const found = traverseToEndpoint(method, callGraph, logger);
+    endpoints.push(...found);
+  }
+  
+  logger.info(`📡 Found ${endpoints.length} affected endpoints`);
+  return endpoints;
+}
+
+function traverseToEndpoint(method, callGraph, logger, visited = new Set(), depth = 0) {
+  // Max depth check
+  if (depth > 10) {
+    logger.verbose('EndpointDetector', `Max depth reached for ${method.name}`);
+    return [];
+  }
+  
+  // Cycle detection with Set (O(1) lookup)
+  if (visited.has(method.name)) return [];
+  visited.add(method.name);
+  
+  logger.verbose('EndpointDetector', `Traversing ${method.name} (depth: ${depth})`);
+  
+  // Check if endpoint
+  if (isHttpEndpoint(method)) {
+    const info = extractEndpointInfo(method);
+    logger.verbose('EndpointDetector', `Found endpoint: ${info.method} ${info.path}`);
+    return [info];
+  }
+  
+  // Traverse callers
+  const endpoints = [];
+  const callers = callGraph.getCallers(method.name) || [];
+  
+  for (const caller of callers) {
+    const found = traverseToEndpoint(caller, callGraph, logger, visited, depth + 1);
+    endpoints.push(...found);
+  }
+  
+  return endpoints;
+}
+
+function isHttpEndpoint(method) {
+  if (!method.decorators) return false;
+  const httpMethods = ['Get', 'Post', 'Put', 'Delete', 'Patch'];
+  return method.decorators.some(d => httpMethods.includes(d.name));
+}
+
+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'
+  );
+  
+  const basePath = controllerDecorator?.arguments?.[0] || '';
+  const subPath = httpDecorator?.arguments?.[0] || '';
+  
+  return {
+    type: 'endpoint',
+    method: httpDecorator.name.toUpperCase(),
+    path: joinPath(basePath, subPath),
+    controller: `${method.class.name}.${method.name}`,
+    file: method.file
+  };
+}
+
+function joinPath(base, sub) {
+  const cleanBase = base.replace(/\/$/, '');
+  const cleanSub = sub.replace(/^\//, '');
+  return cleanSub ? `/${cleanBase}/${cleanSub}`.replace(/\/+/g, '/') : `/${cleanBase}`;
+}
+```
+
+**Verify:**
+```bash
+# Check files created
+ls -la core/detectors/
+ls -la core/utils/logger.js
+
+# Verify no syntax errors
+node -c core/detectors/endpoint-detector.js
+node -c core/utils/logger.js
+```
+
+## Phase 3: Update Imports (One File at a Time)
+
+**Goal:** Switch to new structure gradually
+
+```javascript
+// Find main entry point
+// Example: core/impact-analyzer.js
+
+// Old import
+// import { findEndpoints } from '../modules/api-detector.js';
+
+// New import
+import { findAffectedEndpoints } from './detectors/endpoint-detector.js';
+
+// Update function call
+const endpoints = findAffectedEndpoints(changedMethods, callGraph, { verbose });
+```
+
+**Verify after each change:**
+```bash
+# Test the tool still works
+node cli.js --input=src --base=origin/main --verbose
+
+# Check output is correct
+```
+
+## Phase 4: Remove Unused Code
+
+**Goal:** Clean up old files only after new code is verified
+
+```bash
+# First, verify nothing imports from modules/
+grep -r "from.*modules" --include="*.js" .
+
+# If clear, remove old files
+rm -rf modules/  # Or move to backup first
+```
+
+**Safety:** Keep backup before deleting
+```bash
+mkdir -p .backup
+cp -r modules/ .backup/modules-$(date +%Y%m%d)
+```
+
+## Phase 5: Performance Verification
+
+**Goal:** Ensure optimizations worked
+
+```bash
+# Add timing to verbose output
+# In endpoint-detector.js:
+const startTime = Date.now();
+// ... detection logic
+const duration = Date.now() - startTime;
+logger.verbose('EndpointDetector', `Completed in ${duration}ms`);
+```
+
+**Test with verbose mode:**
+```bash
+node cli.js --input=src --base=origin/main --verbose
+```
+
+**Check:**
+- Is depth limit working? (should see "Max depth reached" if hit)
+- Are visited nodes tracked? (no infinite loops)
+- Is timing shown? (< 50ms per method is good)
+
+## Rollback Strategy
+
+If something breaks:
+
+```bash
+# Restore from backup
+cp -r .backup/modules-YYYYMMDD modules/
+
+# Revert imports in git
+git checkout -- core/impact-analyzer.js
+
+# Or revert entire change
+git reset --hard HEAD
+```
+
+## Acceptance Checklist
+
+- [ ] Phase 1 complete: Current structure documented
+- [ ] Phase 2 complete: New files created in core/
+- [ ] Phase 3 complete: Imports updated, tool still works
+- [ ] Phase 4 complete: Old code removed
+- [ ] Phase 5 complete: Performance verified
+- [ ] Verbose mode works (`--verbose` flag)
+- [ ] Normal mode works (clean output)
+- [ ] No errors in console
+- [ ] Tests pass (if any)
+
+## References
+
+- Task File: `.specify/tasks/task-001-refactor-api-detector.md`
+- API Spec: `.specify/specs/features/api-impact-detection.md`
+- Code Rules: `.github/copilot-instructions.md`

package/.specify/bugs/bug-001-database-detector.md

@@ -0,0 +1,222 @@
+# BUG-001: Database Detector Missing SELECT Operations
+
+**Bug ID:** BUG-001  
+**Status:** ✅ RESOLVED  
+**Priority:** HIGH  
+**Severity:** Medium  
+**Created:** 2025-12-25  
+**Updated:** 2025-12-25  
+**Resolved:** 2025-12-25
+
+---
+
+## Problem Statement
+
+Database detector only catches INSERT/UPDATE/DELETE operations but misses SELECT queries, resulting in incomplete database impact reports.
+
+### Observed Behavior
+
+When code changes include SELECT operations, they are **not detected**:
+
+```typescript
+// ❌ Not detected:
+await repository.find({ where: { status: 'active' } });
+await repository.findOne({ where: { id } });
+await queryBuilder.select(['name', 'email']).getMany();
+```
+
+### Expected Behavior
+
+All database operations including SELECT should be detected and reported in the impact analysis.
+
+---
+
+## Root Cause
+
+**File:** `core/detectors/database-detector.js` (line ~295)
+
+The `typeOrmOps` mapping object only includes write operations (INSERT/UPDATE/DELETE) and does not include read operations (SELECT):
+
+```javascript
+const typeOrmOps = {
+  'insert': 'INSERT',
+  'save': 'INSERT/UPDATE',
+  'create': 'INSERT',
+  'update': 'UPDATE',
+  'merge': 'UPDATE',
+  'delete': 'DELETE',
+  'remove': 'DELETE',
+  'softDelete': 'SOFT_DELETE',
+  // ❌ Missing: find, findOne, select, query, getMany, getOne
+};
+```
+
+The `analyzeChangedCodeForDatabaseOps()` method iterates through this map to detect database operations. Since SELECT operations are not in the map, they are skipped.
+
+---
+
+## Fix Strategy
+
+### Approach
+
+Add SELECT operation methods to the `typeOrmOps` mapping. This is a **low-risk, non-breaking change** that extends existing detection without modifying the core logic.
+
+### Implementation
+
+**Step 1:** Locate the `typeOrmOps` definition in `core/detectors/database-detector.js` (~line 295)
+
+**Step 2:** Add SELECT operations:
+
+```javascript
+const typeOrmOps = {
+  // Existing operations (keep as-is)
+  'insert': 'INSERT',
+  'save': 'INSERT/UPDATE',
+  'create': 'INSERT',
+  'update': 'UPDATE',
+  'merge': 'UPDATE',
+  'delete': 'DELETE',
+  'remove': 'DELETE',
+  'softDelete': 'SOFT_DELETE',
+  
+  // Add SELECT operations
+  'find': 'SELECT',
+  'findOne': 'SELECT',
+  'findBy': 'SELECT',
+  'findOneBy': 'SELECT',
+  'findAndCount': 'SELECT',
+  'select': 'SELECT',
+  'query': 'SELECT',
+  'getMany': 'SELECT',
+  'getOne': 'SELECT',
+};
+```
+
+**Step 3:** No other changes needed. The existing `analyzeChangedCodeForDatabaseOps()` method will automatically handle SELECT operations.
+
+### Why This Works
+
+The method already:
+1. Iterates through `typeOrmOps` entries
+2. Detects method calls matching the keys
+3. Adds operations to the `operations` Set
+4. Formats output correctly
+
+Adding new keys will be processed by the existing logic flow.
+
+---
+
+## Verification
+
+### Test Case
+
+```bash
+# Create a test diff with SELECT operations
+cat > test.diff << 'EOF'
++ await repository.find({ where: { id } });
++ await repository.findOne({ where: { status: 'active' } });
++ const users = await queryBuilder.select(['id', 'name']).getMany();
+EOF
+
+# Run detector and verify output contains:
+# - operations: ["SELECT"]
+# - Correct table detection
+```
+
+### Expected Output
+
+```javascript
+{
+  tableName: "users",
+  modelName: "UserEntity",
+  operations: ["SELECT"],  // ✅ Now detected
+  fields: ["id", "name", "status"],
+  severity: "low"  // SELECT is typically low severity
+}
+```
+
+---
+
+## Impact Assessment
+
+### Risk Level: **LOW** ✅
+
+**Why Low Risk:**
+- Only adds new entries to existing map
+- No changes to detection logic
+- No changes to data structures
+- Backward compatible (existing detections unaffected)
+
+### Areas Affected
+
+| Component | Change Type | Risk |
+|-----------|-------------|------|
+| `database-detector.js` | Addition only | Low |
+| Report output | Enhanced data | None |
+| Existing detections | None | None |
+
+### Testing Required
+
+- [ ] Unit test: Verify SELECT operations are detected
+- [ ] Integration test: Check report includes SELECT in operations array
+- [ ] Regression test: Verify existing INSERT/UPDATE/DELETE still work
+
+---
+
+## Implementation Checklist
+
+- [x] Update `typeOrmOps` in `database-detector.js`
+- [x] Test with `find()` operation
+- [x] Test with `findOne()` operation
+- [x] Test with `select()` operation
+- [x] Test with `query()` operation
+- [x] Verify report output shows SELECT
+- [x] Check console output displays correctly
+- [x] Verify JSON output includes SELECT
+- [ ] Update CHANGELOG if needed
+- [x] Mark bug as RESOLVED
+
+---
+
+## References
+
+**Code Files:**
+- `core/detectors/database-detector.js` (line ~295)
+- `core/report-generator.js` (displays operations)
+
+**Related:**
+- Task 002: `.specify/tasks/task-002-database-detector.md`
+- Spec: `.specify/specs/features/database-impact-detection.md`
+
+**TypeORM Documentation:**
+- Repository API: https://typeorm.io/repository-api
+- Select operations: `find`, `findOne`, `findBy`, etc.
+
+---
+
+## Notes
+
+- SELECT operations should be marked as lower severity than write operations
+- This fix will make reports more complete and accurate
+- Future enhancement: Track which fields are being selected
+
+---
+
+**Estimated Effort:** 5 minutes  
+**Actual Effort:** 3 minutes
+
+---
+
+## Resolution Summary
+
+**Fixed on:** 2025-12-25
+
+**Changes Made:**
+1. Updated `typeOrmOps` map in `analyzeChangedCodeForDatabaseOps()` method (line 295)
+2. Updated `typeOrmOps` map in `detectDatabaseOperationFromCall()` method (line 552)
+3. Added 9 SELECT operation methods: find, findOne, findBy, findOneBy, findAndCount, select, query, getMany, getOne
+
+**Files Modified:**
+- `core/detectors/database-detector.js` (2 locations updated)
+
+**Result:** SELECT operations are now fully detected and will appear in database impact reports.