@sun-asterisk/impact-analyzer 1.0.0

package/README.md

@@ -0,0 +1,506 @@
+# Impact Analyzer
+
+Automated impact analysis tool for TypeScript/JavaScript projects. Analyzes code changes between git references and generates comprehensive impact reports.
+
+## Overview
+
+Impact Analyzer is a powerful tool designed to help development teams understand the full impact of code changes in their TypeScript/JavaScript projects. It detects changes between git commits/branches and automatically analyzes:
+
+- **API Endpoints** - Which REST APIs are affected by the changes
+- **Database Operations** - Which database tables and fields are impacted
+- **Pages/Components** - Which UI components and pages are modified
+- **Logic Impact** - Function call dependencies and impact scope
+- **Test Coverage** - Recommended test cases based on changes
+
+### Key Benefits
+
+- 🎯 **Reduce Testing Effort** - Know exactly what to test instead of full regression
+- 🚀 **Faster Code Reviews** - Reviewers can quickly understand the scope of changes
+- 📊 **Risk Assessment** - Automatically calculates impact scores and severity levels
+- 🔍 **Dependency Tracking** - Identifies all files and functions affected by changes
+- 📝 **Automated Reports** - Generates detailed markdown and JSON reports
+
+## Analysis Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                    1. GIT CHANGE DETECTION                          │
+│  ┌──────────────┐      ┌─────────────┐      ┌──────────────┐      │
+│  │ Git Diff     │ ───> │ Changed     │ ───> │ AST Parser   │      │
+│  │ (base→head)  │      │ Files       │      │ (Symbols)    │      │
+│  └──────────────┘      └─────────────┘      └──────────────┘      │
+└─────────────────────────────────────────────────────────────────────┘
+                                 │
+                                 ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│           2. METHOD-LEVEL CALL GRAPH (ts-morph)                     │
+│  ┌──────────────┐      ┌─────────────┐      ┌──────────────┐      │
+│  │ Parse TS/JS  │ ───> │ Extract     │ ───> │ Build Call   │      │
+│  │ Files        │      │ Methods     │      │ Graph Maps   │      │
+│  └──────────────┘      └─────────────┘      └──────────────┘      │
+│                                                                     │
+│  ⚡ OPTIMIZED: Only parses source files, skips loading all to RAM  │
+│  • method → [methods it calls]      (forward map)                  │
+│  • method → [callers]                (reverse map)                 │
+│  • method → endpoint info            (HTTP decorators)             │
+└─────────────────────────────────────────────────────────────────────┘
+                                 │
+                                 ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                    3. IMPACT DETECTION                              │
+│                                                                     │
+│  ┌────────────────────────┐        ┌───────────────────────┐      │
+│  │  ENDPOINT DETECTOR     │        │  DATABASE DETECTOR    │      │
+│  ├────────────────────────┤        ├───────────────────────┤      │
+│  │ Changed Method         │        │ Changed Method        │      │
+│  │        ↓               │        │        ↓              │      │
+│  │ Traverse Call Graph ↑  │        │ Find Repository       │      │
+│  │        ↓               │        │ Methods ↓             │      │
+│  │ Find Callers           │        │ Detect DB Ops         │      │
+│  │        ↓               │        │ (TypeORM/Prisma)      │      │
+│  │ Filter @Get/@Post      │        │        ↓              │      │
+│  │        ↓               │        │ Extract Tables/Fields │      │
+│  │ 📡 Affected Endpoints  │        │ 💾 DB Impact          │      │
+│  └────────────────────────┘        └───────────────────────┘      │
+│                                                                     │
+│  Flow: Repository → Service → Controller → @Endpoint               │
+└─────────────────────────────────────────────────────────────────────┘
+                                 │
+                                 ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│               4. LOGIC IMPACT ANALYSIS                              │
+│  ┌──────────────┐      ┌─────────────┐      ┌──────────────┐      │
+│  │ Direct       │ ───> │ Indirect    │ ───> │ Risk Level   │      │
+│  │ Callers      │      │ Callers     │      │ Calculation  │      │
+│  └──────────────┘      └─────────────┘      └──────────────┘      │
+│                                                                     │
+│  Uses method call graph for accurate caller tracking               │
+└─────────────────────────────────────────────────────────────────────┘
+                                 │
+                                 ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│               5. IMPACT SCORE CALCULATION                           │
+│                                                                     │
+│   Score = (Endpoints × 10) + (DB Tables × 5) +                     │
+│           (Direct Callers × 3) + (Indirect Callers × 1)            │
+│                                                                     │
+│   Multipliers:                                                      │
+│   • High Risk Logic: ×1.5                                           │
+│   • DB Migration: +20                                               │
+└─────────────────────────────────────────────────────────────────────┘
+                                 │
+                                 ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                  6. REPORT GENERATION                               │
+│                                                                     │
+│   Score → Severity: 🟢 LOW | 🟡 MEDIUM | 🟠 HIGH | 🔴 CRITICAL     │
+│                                                                     │
+│   ┌────────────┐   ┌────────────┐   ┌────────────┐                │
+│   │ Console    │   │ Markdown   │   │ JSON       │                │
+│   │ Report     │   │ Report     │   │ (CI/CD)    │                │
+│   └────────────┘   └────────────┘   └────────────┘                │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### Architecture Highlights
+
+**Layer-Aware Tracking**
+```
+Controller (@Get/@Post) ──┐
+         ↑                │
+      Service             │ Call Graph
+         ↑                │ Traversal
+    Repository            │
+         ↑                │
+    Database ─────────────┘
+```
+
+**Component Separation**
+- `MethodCallGraph`: Pure graph construction logic (no logging)
+- `EndpointDetector`: Endpoint impact analysis + verbose logging
+- `DatabaseDetector`: Database impact analysis + verbose logging
+- `ImpactAnalyzer`: Orchestration and aggregation
+
+## Features
+
+### 1. Change Detection
+- Detects modified, added, and deleted files between git references
+- Extracts changed symbols (functions, classes, methods) using AST parsing
+- Categorizes files by type (source, test, config)
+- Calculates line changes for each file
+
+### 2. API Endpoint Analysis
+- Automatically detects affected REST API endpoints
+- Supports multiple frameworks:
+  - NestJS decorators (`@Get()`, `@Post()`, etc.)
+  - Express routes (`app.get()`, `router.post()`, etc.)
+  - Fastify routes
+- Groups endpoints by controller
+- Shows impact level for each endpoint
+
+### 3. Database Impact Analysis
+- Detects database operations across ORMs:
+  - Prisma
+  - TypeORM
+  - Sequelize
+- Identifies affected tables and fields
+- Lists database operations (CREATE, UPDATE, DELETE, etc.)
+- Checks for migration files
+- Shows sample queries
+
+### 4. Pages/Components Detection
+- Automatically detects UI changes
+- Supports:
+  - Pages (React, Next.js, Vue, etc.)
+  - Components
+  - Views
+  - Screens (React Native)
+- Groups by type for easy review
+- Shows status and line changes
+
+### 5. Logic Impact Analysis
+- Builds dependency graphs
+- Finds direct and indirect callers of changed functions
+- Calculates risk levels based on impact scope
+- Detects control flow changes
+
+### 7. Comprehensive Reporting
+- **Markdown Reports** - Formatted, readable reports with tables and sections
+- **JSON Reports** - Machine-readable output for CI/CD integration
+- **Console Output** - Quick summary with color-coded severity
+- **Impact Scoring** - Numerical score based on change magnitude
+
+## Configuration
+
+### Command Line Options
+
+```bash
+node index.js [OPTIONS]
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--input=DIR` | Source directory to analyze | `src` |
+| `--base=REF` | Base git reference (branch/commit) | `origin/main` |
+| `--head=REF` | Head git reference (branch/commit) | `HEAD` |
+| `--exclude=PATHS` | Comma-separated paths to exclude | `node_modules,dist,build,specs,coverage` |
+| `--output=FILE` | Output markdown file path | `impact-report.md` |
+| `--json=FILE` | Optional JSON output file | - |
+| `--max-depth=N` | Maximum dependency traversal depth | `3` |
+| `--include-tests` | Include test files in analysis | `false` |
+| `--no-fail` | Don't exit with error on critical impact | `false` |
+| `--verbose` | Show verbose output | `false` |
+
+### Configuration File
+
+Default configuration in `config/default-config.js`:
+
+```javascript
+{
+  sourceDir: 'src',
+  excludePaths: ['node_modules', 'dist', 'build', 'specs', 'coverage'],
+  baseRef: 'origin/main',
+  headRef: 'HEAD',
+  maxDepth: 3,
+  includeTests: false,
+  verbose: false,
+  outputFormat: 'markdown',
+  outputFile: 'impact-report.md'
+}
+```
+
+### Environment Setup
+
+1. **Prerequisites**
+   - Node.js 16+ 
+   - Git repository
+   - npm or yarn
+
+2. **Installation**
+   ```bash
+   cd impact-analyzer
+   npm install
+   # or
+   yarn install
+   ```
+
+## Usage
+
+### Basic Usage
+
+Analyze changes between current branch and main:
+
+```bash
+node index.js --input=src --base=origin/main --head=HEAD
+```
+
+### Using the Shell Script
+
+The included shell script provides a convenient wrapper:
+
+```bash
+# Make it executable
+chmod +x run-impact-analysis.sh
+
+# Run with defaults
+./run-impact-analysis.sh
+
+# Run with custom options
+./run-impact-analysis.sh --input=src --base=origin/develop --output=report.md
+```
+
+### NPM Scripts
+
+```bash
+# Analyze local changes
+npm run analyze:local
+
+# Custom analysis
+npm run analyze -- --input=src --base=main --json=impact.json
+```
+
+### Common Scenarios
+
+#### 1. Analyze PR Changes
+
+```bash
+# Compare feature branch against main
+node index.js \
+  --input=src \
+  --base=origin/main \
+  --head=HEAD \
+  --output=pr-impact.md
+```
+
+#### 2. Analyze Specific Commit Range
+
+```bash
+# Compare two commits
+node index.js \
+  --input=src \
+  --base=abc123 \
+  --head=def456 \
+  --output=commit-impact.md
+```
+
+#### 3. Generate JSON Report for CI/CD
+
+```bash
+# Generate both markdown and JSON
+node index.js \
+  --input=src \
+  --base=origin/main \
+  --head=HEAD \
+  --output=impact-report.md \
+  --json=impact-report.json
+```
+
+#### 4. Analyze with Verbose Output
+
+```bash
+# Show detailed logs
+node index.js \
+  --input=src \
+  --base=origin/main \
+  --verbose
+```
+
+#### 5. Continue on Critical Impact
+
+```bash
+# Don't fail CI on critical severity
+node index.js \
+  --input=src \
+  --base=origin/main \
+  --no-fail
+```
+
+### CI/CD Integration
+
+#### GitHub Actions Example
+
+```yaml
+name: Impact Analysis
+
+on:
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+      
+      - name: Install Dependencies
+        run: |
+          cd impact-analyzer
+          npm install
+      
+      - name: Run Impact Analysis
+        run: |
+          cd impact-analyzer
+          node index.js \
+            --input=../src \
+            --base=origin/${{ github.base_ref }} \
+            --head=HEAD \
+            --output=impact-report.md \
+            --json=impact-report.json
+      
+      - name: Upload Report
+        uses: actions/upload-artifact@v3
+        with:
+          name: impact-report
+          path: impact-analyzer/impact-report.md
+      
+      - name: Comment PR
+        uses: actions/github-script@v6
+        with:
+          script: |
+            const fs = require('fs');
+            const report = fs.readFileSync('impact-analyzer/impact-report.md', 'utf8');
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: report
+            });
+```
+
+#### GitLab CI Example
+
+```yaml
+impact_analysis:
+  stage: test
+  script:
+    - cd impact-analyzer
+    - npm install
+    - |
+      node index.js \
+        --input=../src \
+        --base=origin/main \
+        --head=HEAD \
+        --output=impact-report.md \
+        --json=impact-report.json
+  artifacts:
+    paths:
+      - impact-analyzer/impact-report.md
+      - impact-analyzer/impact-report.json
+    reports:
+      dotenv: impact-analyzer/impact-report.json
+```
+
+### Reading the Report
+
+The generated report includes:
+
+1. **📊 Summary** - Overview of changes and severity
+2. **📡 Affected API Endpoints** - List of impacted APIs grouped by controller
+3. **💾 Database Impact** - Tables, fields, and operations affected
+4. **📄 Affected Pages/Components** - UI changes grouped by type
+5. **🔄 Logic Impact** - Call dependencies and risk level
+6. **✅ Recommended Test Cases** - Suggested tests based on changes
+7. **📝 Changed Files** - Complete list of modified files
+
+#### Severity Levels
+
+- 🟢 **LOW** (0-20 points) - Minor changes, low risk
+- 🟡 **MEDIUM** (21-50 points) - Moderate impact, standard testing required
+- 🟠 **HIGH** (51-100 points) - Significant impact, thorough testing needed
+- 🔴 **CRITICAL** (100+ points) - Major changes, full regression testing recommended
+
+#### Impact Scoring
+
+The impact score is calculated based on:
+- Affected endpoints: +10 points each
+- Database tables impacted: +5 points each
+- Direct function callers: +3 points each
+- Indirect function callers: +1 point each
+- High risk logic: 1.5x multiplier
+- Database migration: +20 points
+
+### Example Output
+
+```markdown
+# 🔍 Impact Analysis Report
+
+## 📊 Summary
+
+| Metric | Value |
+|--------|-------|
+| Files Changed | 5 |
+| Symbols Modified | 12 |
+| Impact Score | **45** |
+| Severity | 🟡 **MEDIUM** |
+
+## 📡 Affected API Endpoints
+
+**Total Endpoints Affected:** 3
+
+### Endpoint List
+| Method | Path | Controller | Impact |
+|--------|------|------------|--------|
+| **GET** | `/api/users` | UserController | 🟡 medium |
+| **POST** | `/api/users` | UserController | 🔴 high |
+
+## 💾 Database Impact
+
+**Total Tables Affected:** 2
+
+### Tables Summary
+| Table | Operations | Fields Count | Migration |
+|-------|------------|--------------|-----------|
+| `users` | UPDATE | 3 | ✅ Yes |
+| `profiles` | CREATE, UPDATE | 5 | ❌ No |
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"Source directory does not exist"**
+   - Ensure the `--input` path is correct and relative to the analyzer directory
+
+2. **"Base ref does not exist"**
+   - Run `git fetch` to ensure remote branches are up to date
+   - Verify the branch/commit exists: `git show origin/main`
+
+3. **"No changes detected"**
+   - Check if there are actual differences: `git diff origin/main HEAD`
+   - Ensure you're in a git repository
+
+4. **Parse errors for certain files**
+   - The analyzer uses Babel parser with common plugins
+   - Some experimental syntax may not be supported
+   - These files will be logged and skipped
+
+### Debug Mode
+
+Run with verbose flag to see detailed logs:
+
+```bash
+node index.js --input=src --base=origin/main --verbose
+```
+
+## Contributing
+
+Contributions are welcome! Please ensure:
+- Code follows existing style (no spaces after dots)
+- All functions have single responsibility
+- Use descriptive variable and function names
+- Add tests for new features
+
+## License
+
+MIT
+
+## Support
+
+For issues, questions, or suggestions, please create an issue in the repository.

package/cli.js

@@ -0,0 +1,38 @@
+/**
+ * CLI - Command Line Interface Parser
+ * Handles argument parsing and validation
+ */
+
+export class CLI {
+  constructor(argv) {
+    this.args = new Map();
+    this.parseArgs(argv);
+  }
+
+  parseArgs(argv) {
+    for (let i = 2; i < argv.length; i++) {
+      const arg = argv[i];
+
+      if (arg.startsWith('--')) {
+        const [key, value] = arg.substring(2).split('=');
+        this.args.set(key, value || 'true');
+      } else if (arg.startsWith('-')) {
+        // Short flags
+        const key = arg.substring(1);
+        this.args.set(key, 'true');
+      }
+    }
+  }
+
+  getArg(key, defaultValue = '') {
+    return this.args.get(key) || defaultValue;
+  }
+
+  hasArg(key) {
+    return this.args.has(key);
+  }
+
+  getAllArgs() {
+    return Object.fromEntries(this.args);
+  }
+}

package/config/default-config.js

@@ -0,0 +1,56 @@
+/**
+ * Configuration Loader
+ * Loads and validates configuration from CLI args and defaults
+ */
+
+export function loadConfig(cli) {
+  const config = {
+    // Source directory to analyze
+    sourceDir: cli.getArg('input', 'src'),
+
+    // Paths to exclude from analysis
+    excludePaths: cli.getArg('exclude', 'node_modules,dist,build,specs,coverage')
+      .split(',')
+      .map(p => p.trim()),
+
+    // Git references
+    baseRef: cli.getArg('base', 'origin/main'),
+    headRef: cli.getArg('head', 'HEAD'),
+
+    // Analysis options
+    maxDepth: parseInt(cli.getArg('max-depth', '3')),
+    includeTests: cli.hasArg('include-tests'),
+    verbose: cli.hasArg('verbose'),
+
+    // Report options
+    outputFormat: cli.getArg('format', 'markdown'),
+    outputFile: cli.getArg('output', 'impact-report.md'),
+  };
+
+  // Validate configuration
+  validateConfig(config);
+
+  return config;
+}
+
+function validateConfig(config) {
+  if (!config.sourceDir) {
+    throw new Error('Source directory (--input) is required');
+  }
+
+  if (!config.baseRef || !config.headRef) {
+    throw new Error('Git references (--base and --head) are required');
+  }
+}
+
+export const DEFAULT_CONFIG = {
+  sourceDir: 'src',
+  excludePaths: ['node_modules', 'dist', 'build', 'specs', 'coverage'],
+  baseRef: 'origin/main',
+  headRef: 'HEAD',
+  maxDepth: 3,
+  includeTests: false,
+  verbose: false,
+  outputFormat: 'markdown',
+  outputFile: 'impact-report.md',
+};