🛡️ DepGuardian

A powerful CLI tool for analyzing and resolving dependency conflicts in JavaScript and TypeScript projects.

Features

• Detect version conflicts - Find packages with multiple installed versions
• Trace root causes - Identify which dependencies need updating
• Smart suggestions - Get exact version recommendations (e.g., "Update: [email protected] → 3.0.0")
• Peer dependency checks - Detect missing or incompatible peer dependencies
• Multi-format support - Works with npm, yarn, and pnpm
• Fast analysis - Instant for peer-only conflicts, 2-3s for version conflicts
• Multiple outputs - Terminal, JSON, or HTML reports
• Language-agnostic - Works with JavaScript, TypeScript, and any framework

Installation

# Global installation
npm install -g depguardian

# As dev dependency (recommended)
npm install --save-dev depguardian

Usage

Basic Commands

# Scan for conflicts
depguardian scan

# Resolve conflicts interactively
depguardian resolve --interactive

# Auto-update packages
depguardian update

# Visualize dependency graph
depguardian graph

# CI mode (fails on conflicts)
depguardian ci

Scan Options

depguardian scan [path]                    # Scan project
depguardian scan --verbose                 # Show full dependency tree
depguardian scan --format json             # JSON output
depguardian scan --format html -o report.html  # HTML report

Resolve Options

depguardian resolve --interactive          # Choose resolutions manually
depguardian resolve --auto                 # Apply safe resolutions automatically
depguardian resolve --simulate             # Preview changes without applying

Other Commands

depguardian update [--dry-run]            # Update packages to resolve conflicts
depguardian graph [--package name]        # Visualize dependency tree
depguardian graph --conflicts-only        # Show only conflicting packages
depguardian clean                         # Clean and regenerate lockfile
depguardian ci [--severity high]          # CI mode with severity threshold
depguardian monorepo [--pattern "apps/*"] # Scan monorepo packages

How It Works

1. Parses lockfile - Reads package-lock.json, yarn.lock, or pnpm-lock.yaml
2. Builds dependency tree - Maps all direct and transitive dependencies
3. Detects conflicts - Finds packages with multiple installed versions
4. Traces parents - Identifies which direct dependencies cause conflicts
5. Queries npm registry - Finds exact compatible versions (only for version conflicts)
6. Generates suggestions - Provides actionable recommendations

Conflict Types

Version Conflicts

Multiple versions of the same package installed.

Peer Dependency Conflicts

Missing or incompatible peer dependencies.

Output Formats

• Terminal
• JSON
• HTML

Configuration (Optional)

DepGuardian works out of the box with no configuration. Optionally create .depguardianrc.json to customize behavior:

{
  "severity": "medium",
  "ignore": ["optional-package"],
  "rules": {
    "react": "^18.0.0"
  }
}

Programmatic API

const depguardian = require("depguardian");

// Analyze a project
const analysis = await depguardian.analyze("/path/to/project");
console.log("Conflicts:", analysis.conflicts.length);

// Resolve conflicts
await depConflictResolver.resolve("/path/to/project", { auto: true });

Contributing

See CONTRIBUTING.md for development guidelines.

License

MIT © DepGuardian Contributors

Note: DepGuardian detects version conflicts, not security vulnerabilities. Use npm audit for security scanning.