devcompass 2.1.0 → 2.3.0

package/README.md

@@ -6,21 +6,26 @@
 [![npm downloads](https://img.shields.io/npm/dm/devcompass.svg)](https://www.npmjs.com/package/devcompass)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Analyze your JavaScript projects to find unused dependencies, outdated packages, **detect known security issues**, and **automatically fix them** with a single command.
+Analyze your JavaScript projects to find unused dependencies, outdated packages, **detect security vulnerabilities**, **check bundle sizes**, **verify licenses**, and **automatically fix issues** with a single command. Perfect for **CI/CD pipelines** with JSON output and exit codes.
 
+> **NEW in v2.3:** Security scanning, bundle analysis & license checker! 🔐  
+> **NEW in v2.2:** CI/CD integration with JSON output & smart caching! 🚀  
 > **NEW in v2.1:** Auto-fix command! 🔧 Fix critical issues automatically!  
 > **NEW in v2.0:** Real-time ecosystem alerts for known issues! 🚨
 
 ## ✨ Features
 
-- 🔧 **Auto-Fix Command** (NEW in v2.1!) - Fix issues automatically with one command
-- 🚨 **Ecosystem Intelligence** - Detect known issues before they break production
+- 🔐 **Security Scanning** (NEW in v2.3!) - npm audit integration with severity breakdown
+- 📦 **Bundle Size Analysis** (NEW in v2.3!) - Identify heavy packages (> 1MB)
+- ⚖️ **License Checker** (NEW in v2.3!) - Detect restrictive licenses (GPL, AGPL)
+- 🚀 **CI/CD Integration** (v2.2) - JSON output, exit codes, and silent mode
+- ⚡ **Smart Caching** (v2.2) - 70% faster on repeated runs
+- 🎛️ **Advanced Filtering** (v2.2) - Control alerts by severity level
+- 🔧 **Auto-Fix Command** (v2.1) - Fix issues automatically with one command
+- 🚨 **Ecosystem Intelligence** (v2.0) - Detect known issues before they break production
 - 🔍 **Detect unused dependencies** - Find packages you're not actually using
-- 📦 **Check for outdated packages** - See what needs updating
-- 🔐 **Security alerts** - Critical vulnerabilities and deprecated packages
 - 📊 **Project health score** - Get a 0-10 rating for your dependencies
 - 🎨 **Beautiful terminal UI** - Colored output with severity indicators
-- ⚡ **Fast analysis** - Scans projects in seconds
 - 🔧 **Framework-aware** - Handles React, Next.js, Angular, NestJS, PostCSS, Tailwind
 
 ## 🚀 Installation
@@ -42,189 +47,375 @@ npx devcompass analyze
 
 ## 📖 Usage
 
-### Analyze Your Project
-Navigate to your project directory and run:
+### Basic Commands
 ```bash
+# Analyze your project
 devcompass analyze
-```
 
-### Auto-Fix Issues (NEW in v2.1!)
-Automatically fix detected issues:
-```bash
+# Auto-fix issues
 devcompass fix
+
+# JSON output (for CI/CD)
+devcompass analyze --json
+
+# CI mode (exit code 1 if score < threshold)
+devcompass analyze --ci
+
+# Silent mode (no output)
+devcompass analyze --silent
 ```
 
-## 🔧 Auto-Fix Command (NEW in v2.1!)
+## 🔐 NEW in v2.3: Security & Compliance Features
 
-DevCompass can now **automatically fix issues** in your project!
+### Security Vulnerability Scanning
 
-### What it does:
-- 🔴 **Fixes critical security issues** - Upgrades packages with known vulnerabilities
-- 🧹 **Removes unused dependencies** - Cleans up packages you're not using
-- ⬆️ **Safe updates** - Applies patch and minor updates automatically
-- ⚠️ **Skips breaking changes** - Major updates require manual review
+DevCompass now integrates with **npm audit** to detect security vulnerabilities automatically!
 
-### Usage
-```bash
-# Interactive mode (asks for confirmation)
-devcompass fix
+**Example Output:**
+```
+🔐 SECURITY VULNERABILITIES (12)
 
-# Auto-apply without confirmation
-devcompass fix --yes
-devcompass fix -y
+  🔴 CRITICAL: 2
+  🟠 HIGH: 4
+  🟡 MODERATE: 5
+  ⚪ LOW: 1
 
-# Fix specific directory
-devcompass fix --path /path/to/project
+  Run npm audit fix to fix vulnerabilities
+```
+
+**How it works:**
+1. Runs `npm audit` in the background
+2. Parses vulnerability data
+3. Shows severity breakdown
+4. Impacts health score (-2.5 per critical issue)
+5. Suggests fix commands
+
+**Health Score Impact:**
+- Critical: −2.5 points each
+- High: −1.5 points each
+- Moderate: −0.5 points each
+- Low: −0.2 points each
+
+### Bundle Size Analysis
+
+Identify large dependencies that bloat your `node_modules`!
+
+**Example Output:**
+```
+📦 HEAVY PACKAGES (3)
+
+  Packages larger than 1MB:
+
+  webpack                   2.3 MB
+  typescript                8.1 MB
+  @tensorflow/tfjs          12.4 MB
 ```
 
-### Example Output
+**Perfect for:**
+- Frontend developers optimizing bundle size
+- Identifying unnecessary large dependencies
+- Web performance optimization
+- Docker image size reduction
+
+### License Compliance Checker
+
+Detect restrictive licenses that may require legal review!
+
+**Example Output:**
 ```
-🔧 DevCompass Fix - Analyzing and fixing your project...
+⚖️ LICENSE WARNINGS (2)
+
+  sharp - Restrictive (LGPL-3.0)
+  custom-lib - Unknown (UNLICENSED)
 
-🔴 CRITICAL ISSUES TO FIX:
+  Note: Restrictive licenses may require legal review
+```
 
-🔴 lodash@4.17.19
-   Issue: Prototype pollution vulnerability
-   Fix: Upgrade to 4.17.21
+**What gets flagged:**
+- **Restrictive licenses:** GPL, AGPL, LGPL (may require source code disclosure)
+- **Unknown licenses:** Packages without license information
+- **Unlicensed packages:** Legal risk for commercial use
 
-🟠 axios@1.6.0
-   Issue: Memory leak in request interceptors
-   Fix: Upgrade to 1.6.2
+**Supported licenses:**
+- ✅ **Safe:** MIT, Apache-2.0, BSD, ISC, CC0
+- ⚠️ **Restrictive:** GPL, AGPL, LGPL
+- ❓ **Unknown:** Missing or custom licenses
+
+### Combined Analysis Example (v2.3)
+
+**Full Output:**
+```
+🔍 DevCompass v2.3.0 - Analyzing your project...
+✔ Scanned 25 dependencies in project
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-🧹 UNUSED DEPENDENCIES TO REMOVE:
+🔐 SECURITY VULNERABILITIES (5)
 
-  ● moment
-  ● express
+  🔴 CRITICAL: 1
+  🟠 HIGH: 2
+  🟡 MODERATE: 2
+
+  Run npm audit fix to fix vulnerabilities
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-⬆️  SAFE UPDATES (patch/minor):
+🚨 ECOSYSTEM ALERTS (1)
 
-  react-dom: 18.2.0 → 18.2.1 (patch update)
+🟠 HIGH
+  axios@1.6.0
+    Issue: Memory leak in request interceptors
+    Fix: 1.6.2
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-⚠️  MAJOR UPDATES (skipped - may have breaking changes):
+📦 HEAVY PACKAGES (2)
+
+  Packages larger than 1MB:
+
+  typescript                8.1 MB
+  webpack                   2.3 MB
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-  express: 4.18.0 → 5.2.1
+⚖️ LICENSE WARNINGS (1)
 
-  Run these manually after reviewing changelog:
-  npm install express@5.2.1
+  sharp - Restrictive (LGPL-3.0)
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-📊 FIX SUMMARY:
+📊 PROJECT HEALTH
 
-  Critical fixes:  2
-  Remove unused:   2
-  Safe updates:    1
-  Skipped major:   1
+  Overall Score:              6.2/10
+  Total Dependencies:         25
+  Security Vulnerabilities:   5
+  Ecosystem Alerts:           1
+  Unused:                     0
+  Outdated:                   3
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-❓ Apply these fixes? (y/N): y
+💡 QUICK WINS
+
+  🔐 Fix security vulnerabilities:
+
+  npm audit fix
 
-🔧 Applying fixes...
+  🔴 Fix critical issues:
 
-✔ ✅ Removed 2 unused packages
-✔ ✅ Fixed lodash@4.17.21
-✔ ✅ Fixed axios@1.6.2
-✔ ✅ Updated 1 packages
+  npm install axios@1.6.2
 
-✨ All fixes applied successfully!
+  Expected impact:
+  ✓ Resolve security vulnerabilities
+  ✓ Resolve critical stability issues
+  ✓ Improve health score → 8.7/10
 
-💡 Run devcompass analyze to see the new health score.
+💡 TIP: Run 'devcompass fix' to apply these fixes automatically!
 ```
 
-### Safety Features
-- ✅ Shows what will be changed before applying
-- ✅ Requires confirmation (unless `--yes` flag used)
-- ✅ Skips major updates (may have breaking changes)
-- ✅ Groups actions by priority (critical → cleanup → updates)
-- ✅ Provides clear summary of changes
+## 🚀 CI/CD Integration (v2.2)
 
-### Workflow Example
+### JSON Output
+Perfect for parsing in CI/CD pipelines:
 ```bash
-# 1. Analyze your project
-devcompass analyze
+devcompass analyze --json
+```
 
-# 2. If issues found, auto-fix them
-devcompass fix
+**Output (v2.3):**
+```json
+{
+  "version": "2.3.0",
+  "timestamp": "2026-04-02T10:30:00.000Z",
+  "summary": {
+    "healthScore": 6.2,
+    "totalDependencies": 25,
+    "securityVulnerabilities": 5,
+    "ecosystemAlerts": 1,
+    "unusedDependencies": 0,
+    "outdatedPackages": 3,
+    "heavyPackages": 2,
+    "licenseWarnings": 1
+  },
+  "security": {
+    "total": 5,
+    "critical": 1,
+    "high": 2,
+    "moderate": 2,
+    "low": 0,
+    "vulnerabilities": [...]
+  },
+  "bundleAnalysis": {
+    "heavyPackages": [
+      { "name": "typescript", "size": "8.1 MB" },
+      { "name": "webpack", "size": "2.3 MB" }
+    ]
+  },
+  "licenses": {
+    "warnings": [
+      { "package": "sharp", "license": "LGPL-3.0", "type": "restrictive" }
+    ]
+  },
+  "ecosystemAlerts": [...],
+  "unusedDependencies": [...],
+  "outdatedPackages": [...]
+}
+```
 
-# 3. Verify the improvements
-devcompass analyze
+### CI Mode
+Automatically fail builds if health score is too low:
+```bash
+devcompass analyze --ci
 ```
 
-## 📊 Analyze Command
+- ✅ **Exit code 0** if score ≥ threshold (default: 7/10)
+- ❌ **Exit code 1** if score < threshold
+
+**GitHub Actions Example:**
+```yaml
+name: Dependency Health Check
 
-### Example Output (v2.1)
+on: [push, pull_request]
+
+jobs:
+  health-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+      - run: npm install
+      - run: npx devcompass analyze --ci
 ```
-🔍 DevCompass v2.1.0 - Analyzing your project...
-✔ Scanned 15 dependencies in project
 
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+### Silent Mode
+For background checks or scripts:
+```bash
+devcompass analyze --silent
+echo $?  # Check exit code
+```
 
-🚨 ECOSYSTEM ALERTS (2)
+## ⚡ Smart Caching (v2.2)
 
-🔴 CRITICAL
-  lodash@4.17.19
-    Issue: Prototype pollution vulnerability
-    Affected: <4.17.21
-    Fix: 4.17.21
-    Source: npm advisory 1523
+DevCompass caches results to improve performance:
 
-🟠 HIGH
-  axios@1.6.0
-    Issue: Memory leak in request interceptors
-    Affected: >=1.5.0 <1.6.2
-    Fix: 1.6.2
-    Source: GitHub Issue #5456
+- **First run:** Normal speed (fetches all data)
+- **Cached runs:** ~70% faster
+- **Cache duration:** 1 hour
+- **Cache file:** `.devcompass-cache.json` (auto-gitignored)
 
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+**What gets cached:**
+- Security vulnerabilities
+- Ecosystem alerts
+- Unused dependencies
+- Outdated packages
+- Bundle sizes
+- License information
 
-🔴 UNUSED DEPENDENCIES (2)
-  ● moment
-  ● request
+**Disable caching:**
+```json
+// devcompass.config.json
+{
+  "cache": false
+}
+```
 
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+## 🎛️ Advanced Configuration (v2.2)
+
+Create `devcompass.config.json` in your project root:
+```json
+{
+  "ignore": ["lodash", "moment"],
+  "ignoreSeverity": ["low"],
+  "minSeverity": "medium",
+  "minScore": 7,
+  "cache": true
+}
+```
 
-🟡 OUTDATED PACKAGES (3)
-  react          18.2.0 → ^19.0.0  (major update)
-  express        4.18.0 → ^4.19.0  (patch update)
+### Configuration Options
 
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+| Option | Type | Description | Example |
+|--------|------|-------------|---------|
+| `ignore` | `string[]` | Ignore specific packages from alerts | `["lodash", "axios"]` |
+| `ignoreSeverity` | `string[]` | Ignore severity levels | `["low", "medium"]` |
+| `minSeverity` | `string` | Only show alerts above this level | `"high"` (shows critical + high) |
+| `minScore` | `number` | Minimum score for CI mode | `7` (fails if < 7) |
+| `cache` | `boolean` | Enable/disable caching | `true` |
 
-📊 PROJECT HEALTH
-  Overall Score:       5.5/10
-  Total Dependencies:  15
-  Ecosystem Alerts:    2
-  Unused:              2
-  Outdated:            3
+### Severity Levels (highest to lowest)
+1. **critical** - Immediate security risk
+2. **high** - Production stability issues
+3. **medium** - Maintenance concerns
+4. **low** - Minor issues
 
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+### Example Configurations
 
-💡 QUICK WINS
-  🔴 Fix critical issues:
+**Security-focused (strict):**
+```json
+{
+  "minSeverity": "critical",
+  "minScore": 9
+}
+```
 
-  npm install lodash@4.17.21
-  npm install axios@1.6.2
+**Balanced (recommended):**
+```json
+{
+  "ignoreSeverity": ["low"],
+  "minScore": 7
+}
+```
 
-  🧹 Clean up unused dependencies:
+**Relaxed (development):**
+```json
+{
+  "ignoreSeverity": ["low", "medium"],
+  "minScore": 5
+}
+```
 
-  npm uninstall moment request
+## 🔧 Auto-Fix Command (v2.1)
 
-  Expected impact:
-  ✓ Resolve critical security/stability issues
-  ✓ Remove 2 unused packages
-  ✓ Reduce node_modules size
-  ✓ Improve health score → 8.5/10
+DevCompass can **automatically fix issues** in your project!
 
-💡 TIP: Run 'devcompass fix' to apply these fixes automatically!
+### What it does:
+- 🔴 **Fixes critical security issues** - Upgrades packages with known vulnerabilities
+- 🧹 **Removes unused dependencies** - Cleans up packages you're not using
+- ⬆️ **Safe updates** - Applies patch and minor updates automatically
+- ⚠️ **Skips breaking changes** - Major updates require manual review
+
+### Usage
+```bash
+# Interactive mode (asks for confirmation)
+devcompass fix
+
+# Auto-apply without confirmation (for CI/CD)
+devcompass fix --yes
+devcompass fix -y
+
+# Fix specific directory
+devcompass fix --path /path/to/project
+```
+
+### Safety Features
+- ✅ Shows what will be changed before applying
+- ✅ Requires confirmation (unless `--yes` flag used)
+- ✅ Skips major updates (may have breaking changes)
+- ✅ Groups actions by priority (critical → cleanup → updates)
+- ✅ Provides clear summary of changes
+
+### Workflow Example
+```bash
+# 1. Analyze your project
+devcompass analyze
+
+# 2. If issues found, auto-fix them
+devcompass fix
+
+# 3. Verify the improvements
+devcompass analyze
 ```
 
-## 🚨 Ecosystem Intelligence
+## 🚨 Ecosystem Intelligence (v2.0)
 
 DevCompass tracks **real-world issues** in popular packages and warns you before they break production!
 
@@ -277,11 +468,12 @@ DevCompass won't flag these as unused (they're typically used in config files):
 - Shows current vs latest versions
 - Indicates update type (major/minor/patch)
 
-### Health Score (Enhanced in v2.0)
+### Health Score (Enhanced in v2.3)
 Calculated from 0-10 based on:
 - Percentage of unused dependencies (−4 points per 100%)
 - Percentage of outdated packages (−3 points per 100%)
 - Ecosystem alerts by severity (−0.2 to −2.0 per issue)
+- Security vulnerabilities by severity (−0.2 to −2.5 per issue)
 - Higher score = healthier project
 
 ## ⚙️ Commands & Options
@@ -303,17 +495,86 @@ devcompass --help
 devcompass -h
 ```
 
-### Options
+### Analyze Options
 ```bash
-# Analyze/fix specific directory
+# Analyze specific directory
 devcompass analyze --path /path/to/project
+
+# JSON output (for CI/CD)
+devcompass analyze --json
+
+# CI mode (fail if score < threshold)
+devcompass analyze --ci
+
+# Silent mode (no output)
+devcompass analyze --silent
+
+# Combine options
+devcompass analyze --path ./my-project --json
+```
+
+### Fix Options
+```bash
+# Fix specific directory
 devcompass fix --path /path/to/project
 
-# Auto-fix without confirmation
+# Auto-apply without confirmation
 devcompass fix --yes
 devcompass fix -y
 ```
 
+## 🔄 Complete Workflows
+
+### Local Development Workflow
+```bash
+# Check project health
+devcompass analyze
+
+# Fix issues automatically
+devcompass fix
+
+# Verify improvements
+devcompass analyze
+```
+
+### CI/CD Pipeline Workflow
+```bash
+# Analyze and export JSON
+devcompass analyze --json > health-report.json
+
+# Fail build if score too low
+devcompass analyze --ci
+
+# Or combine with other checks
+devcompass analyze --ci && npm test && npm run build
+```
+
+### Pre-commit Hook Workflow
+```bash
+# .husky/pre-commit
+#!/bin/sh
+devcompass analyze --silent
+if [ $? -ne 0 ]; then
+  echo "❌ Dependency health check failed!"
+  exit 1
+fi
+```
+
+### Security-Focused Workflow
+```bash
+# 1. Run security scan
+devcompass analyze
+
+# 2. Check for critical vulnerabilities
+devcompass analyze --json | jq '.security.critical'
+
+# 3. Auto-fix if possible
+npm audit fix
+
+# 4. Verify fixes
+devcompass analyze
+```
+
 ## ⚠️ Known Issues & Best Practices
 
 ### Installation
@@ -332,6 +593,11 @@ DevCompass is smart about config-based dependencies, but occasionally may flag p
 
 If you encounter a false positive, please [report it](https://github.com/AjayBThorat-20/devcompass/issues)!
 
+### Cache Management
+- Cache files (`.devcompass-cache.json`) are automatically gitignored
+- Cache expires after 1 hour
+- Delete cache file manually if needed: `rm .devcompass-cache.json`
+
 ## 🛠️ Requirements
 
 - Node.js >= 14.0.0
@@ -341,9 +607,14 @@ If you encounter a false positive, please [report it](https://github.com/AjayBTh
 
 1. **Run regularly** - Add to your CI/CD pipeline or git hooks
 2. **Use fix command** - Let DevCompass handle routine maintenance
-3. **Fix critical alerts first** - Prioritize security and stability
-4. **Review major updates** - Always check changelogs before major version bumps
-5. **Verify before uninstalling** - DevCompass helps identify candidates, but always verify
+3. **Check security first** - Prioritize fixing critical vulnerabilities
+4. **Monitor bundle size** - Keep an eye on heavy packages
+5. **Review licenses** - Ensure compliance with your legal requirements
+6. **Configure severity levels** - Filter out noise with `minSeverity`
+7. **Enable CI mode** - Catch issues before they reach production
+8. **Use JSON output** - Integrate with your monitoring tools
+9. **Review major updates** - Always check changelogs before major version bumps
+10. **Verify before uninstalling** - DevCompass helps identify candidates, but always verify
 
 ## 🤝 Contributing
 
@@ -427,15 +698,21 @@ Check out DevCompass stats:
 
 ## 🌟 What's Next?
 
-### Roadmap (v2.2+)
+### Roadmap (v2.4+)
 - [x] ~~Automatic fix command~~ ✅ **Added in v2.1!**
-- [ ] Integration with `npm audit` for automated security scanning
-- [ ] CI/CD integration with `--json` output
-- [ ] GitHub Issues API for real-time issue tracking
-- [ ] Web dashboard for team health monitoring
-- [ ] More tracked packages (React, Next.js, Vue, Angular)
-- [ ] Custom ignore rules via config file
-- [ ] Bundle size analysis
+- [x] ~~CI/CD integration with JSON output~~ ✅ **Added in v2.2!**
+- [x] ~~Smart caching system~~ ✅ **Added in v2.2!**
+- [x] ~~Custom ignore rules via config file~~ ✅ **Added in v2.2!**
+- [x] ~~npm audit integration~~ ✅ **Added in v2.3!**
+- [x] ~~Bundle size analysis~~ ✅ **Added in v2.3!**
+- [x] ~~License compliance checker~~ ✅ **Added in v2.3!**
+- [ ] GitHub Issues API for real-time issue tracking (v2.4.0)
+- [ ] Automated security patch suggestions (v2.4.0)
+- [ ] Dependency graph visualization (v2.5.0)
+- [ ] Web dashboard for team health monitoring (v2.5.0)
+- [ ] More tracked packages (React, Next.js, Vue, Angular) (v2.5.0)
+- [ ] Team collaboration features (v2.6.0)
+- [ ] Slack/Discord notifications (v2.6.0)
 
 Want to contribute? Pick an item and open an issue! 🚀
 
@@ -445,4 +722,4 @@ Want to contribute? Pick an item and open an issue! 🚀
 
 *DevCompass - Keep your dependencies healthy!* 🧭
 
-**Like Lighthouse for your dependencies** ⚡
+**Like Lighthouse for your dependencies** ⚡